From f62fb97571c9b1a57b56bd020de0486209c80322 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Wed, 14 Feb 2024 17:14:46 -0500 Subject: [PATCH 1/3] 'npm run gen-api -- -p qiskit -v 1.1.0-dev --dev' --- docs/api/qiskit/dev/_package.json | 2 +- docs/api/qiskit/dev/assembler.md | 6 +- docs/api/qiskit/dev/circuit.md | 4 +- docs/api/qiskit/dev/circuit_classical.md | 70 ++++----- docs/api/qiskit/dev/circuit_library.md | 142 +++++++++--------- docs/api/qiskit/dev/circuit_singleton.md | 6 +- docs/api/qiskit/dev/compiler.md | 8 +- docs/api/qiskit/dev/converters.md | 16 +- docs/api/qiskit/dev/dagcircuit.md | 4 +- docs/api/qiskit/dev/exceptions.md | 14 +- docs/api/qiskit/dev/passmanager.md | 2 +- docs/api/qiskit/dev/providers.md | 10 +- .../api/qiskit/dev/providers_fake_provider.md | 6 +- docs/api/qiskit/dev/pulse.md | 134 ++++++++--------- docs/api/qiskit/dev/qasm2.md | 16 +- docs/api/qiskit/dev/qasm3.md | 16 +- .../qiskit/dev/qiskit.assembler.RunConfig.md | 2 +- .../qiskit/dev/qiskit.circuit.AncillaQubit.md | 2 +- .../dev/qiskit.circuit.AncillaRegister.md | 2 +- docs/api/qiskit/dev/qiskit.circuit.Bit.md | 2 +- .../qiskit/dev/qiskit.circuit.BreakLoopOp.md | 2 +- .../dev/qiskit.circuit.ClassicalRegister.md | 4 +- docs/api/qiskit/dev/qiskit.circuit.Clbit.md | 2 +- .../dev/qiskit.circuit.ContinueLoopOp.md | 2 +- .../dev/qiskit.circuit.ControlFlowOp.md | 2 +- .../dev/qiskit.circuit.ControlledGate.md | 4 +- docs/api/qiskit/dev/qiskit.circuit.Delay.md | 4 +- .../dev/qiskit.circuit.EquivalenceLibrary.md | 2 +- .../qiskit/dev/qiskit.circuit.ForLoopOp.md | 2 +- docs/api/qiskit/dev/qiskit.circuit.Gate.md | 4 +- .../api/qiskit/dev/qiskit.circuit.IfElseOp.md | 2 +- .../qiskit/dev/qiskit.circuit.Instruction.md | 2 +- .../dev/qiskit.circuit.InstructionSet.md | 2 +- .../qiskit/dev/qiskit.circuit.Operation.md | 2 +- .../qiskit/dev/qiskit.circuit.Parameter.md | 8 +- .../dev/qiskit.circuit.ParameterExpression.md | 12 +- .../dev/qiskit.circuit.ParameterVector.md | 2 +- .../dev/qiskit.circuit.QuantumCircuit.md | 6 +- .../dev/qiskit.circuit.QuantumRegister.md | 4 +- docs/api/qiskit/dev/qiskit.circuit.Qubit.md | 2 +- .../api/qiskit/dev/qiskit.circuit.Register.md | 2 +- .../qiskit/dev/qiskit.circuit.SwitchCaseOp.md | 2 +- .../qiskit/dev/qiskit.circuit.WhileLoopOp.md | 2 +- ...uit.classicalfunction.BooleanExpression.md | 4 +- ...uit.classicalfunction.ClassicalFunction.md | 4 +- ...tion.ClassicalFunctionCompilerTypeError.md | 2 +- ...calfunction.ClassicalFunctionParseError.md | 2 +- .../qiskit/dev/qiskit.circuit.library.AND.md | 4 +- .../dev/qiskit.circuit.library.Barrier.md | 2 +- .../dev/qiskit.circuit.library.C3SXGate.md | 2 +- .../dev/qiskit.circuit.library.C3XGate.md | 2 +- .../dev/qiskit.circuit.library.C4XGate.md | 2 +- .../dev/qiskit.circuit.library.CCXGate.md | 2 +- .../dev/qiskit.circuit.library.CCZGate.md | 2 +- ...it.circuit.library.CDKMRippleCarryAdder.md | 4 +- .../dev/qiskit.circuit.library.CHGate.md | 2 +- .../dev/qiskit.circuit.library.CPhaseGate.md | 2 +- .../dev/qiskit.circuit.library.CRXGate.md | 2 +- .../dev/qiskit.circuit.library.CRYGate.md | 2 +- .../dev/qiskit.circuit.library.CRZGate.md | 2 +- .../dev/qiskit.circuit.library.CSGate.md | 2 +- .../dev/qiskit.circuit.library.CSXGate.md | 2 +- .../dev/qiskit.circuit.library.CSdgGate.md | 2 +- .../dev/qiskit.circuit.library.CSwapGate.md | 2 +- .../dev/qiskit.circuit.library.CU1Gate.md | 2 +- .../dev/qiskit.circuit.library.CU3Gate.md | 2 +- .../dev/qiskit.circuit.library.CUGate.md | 2 +- .../dev/qiskit.circuit.library.CXGate.md | 2 +- .../dev/qiskit.circuit.library.CYGate.md | 2 +- .../dev/qiskit.circuit.library.CZGate.md | 2 +- .../dev/qiskit.circuit.library.DCXGate.md | 2 +- .../dev/qiskit.circuit.library.Diagonal.md | 4 +- .../qiskit.circuit.library.DiagonalGate.md | 2 +- .../qiskit.circuit.library.DraperQFTAdder.md | 4 +- .../dev/qiskit.circuit.library.ECRGate.md | 2 +- .../qiskit.circuit.library.EfficientSU2.md | 4 +- ...t.circuit.library.EvolvedOperatorAnsatz.md | 2 +- .../qiskit.circuit.library.ExactReciprocal.md | 2 +- ...it.circuit.library.ExcitationPreserving.md | 2 +- .../qiskit.circuit.library.FourierChecking.md | 2 +- ...ircuit.library.FunctionalPauliRotations.md | 2 +- .../qiskit/dev/qiskit.circuit.library.GMS.md | 2 +- .../qiskit/dev/qiskit.circuit.library.GR.md | 2 +- .../qiskit/dev/qiskit.circuit.library.GRX.md | 4 +- .../qiskit/dev/qiskit.circuit.library.GRY.md | 4 +- .../qiskit/dev/qiskit.circuit.library.GRZ.md | 4 +- .../qiskit.circuit.library.GlobalPhaseGate.md | 2 +- .../dev/qiskit.circuit.library.GraphState.md | 4 +- .../qiskit.circuit.library.GroverOperator.md | 4 +- .../dev/qiskit.circuit.library.HGate.md | 2 +- ...circuit.library.HRSCumulativeMultiplier.md | 4 +- .../qiskit.circuit.library.HamiltonianGate.md | 2 +- ...it.circuit.library.HiddenLinearFunction.md | 4 +- .../dev/qiskit.circuit.library.IGate.md | 2 +- .../qiskit/dev/qiskit.circuit.library.IQP.md | 4 +- .../dev/qiskit.circuit.library.Initialize.md | 2 +- .../qiskit.circuit.library.InnerProduct.md | 4 +- ...iskit.circuit.library.IntegerComparator.md | 4 +- .../dev/qiskit.circuit.library.Isometry.md | 2 +- ...circuit.library.LinearAmplitudeFunction.md | 4 +- .../qiskit.circuit.library.LinearFunction.md | 2 +- ...it.circuit.library.LinearPauliRotations.md | 4 +- .../qiskit/dev/qiskit.circuit.library.MCMT.md | 4 +- .../dev/qiskit.circuit.library.MCMTVChain.md | 4 +- .../dev/qiskit.circuit.library.MCPhaseGate.md | 2 +- .../dev/qiskit.circuit.library.MCXGate.md | 2 +- .../dev/qiskit.circuit.library.MCXGrayCode.md | 2 +- .../qiskit.circuit.library.MCXRecursive.md | 2 +- .../dev/qiskit.circuit.library.MCXVChain.md | 2 +- .../dev/qiskit.circuit.library.MSGate.md | 2 +- .../dev/qiskit.circuit.library.Measure.md | 2 +- .../dev/qiskit.circuit.library.NLocal.md | 6 +- .../qiskit/dev/qiskit.circuit.library.OR.md | 4 +- ...skit.circuit.library.PauliEvolutionGate.md | 2 +- .../qiskit.circuit.library.PauliFeatureMap.md | 4 +- .../dev/qiskit.circuit.library.PauliGate.md | 2 +- .../qiskit.circuit.library.PauliTwoDesign.md | 4 +- .../dev/qiskit.circuit.library.Permutation.md | 4 +- .../qiskit.circuit.library.PermutationGate.md | 2 +- .../qiskit.circuit.library.PhaseEstimation.md | 4 +- .../dev/qiskit.circuit.library.PhaseGate.md | 2 +- .../dev/qiskit.circuit.library.PhaseOracle.md | 4 +- ...skit.circuit.library.PiecewiseChebyshev.md | 4 +- ...t.library.PiecewiseLinearPauliRotations.md | 4 +- ...brary.PiecewisePolynomialPauliRotations.md | 4 +- ...ircuit.library.PolynomialPauliRotations.md | 4 +- .../dev/qiskit.circuit.library.QAOAAnsatz.md | 4 +- .../qiskit/dev/qiskit.circuit.library.QFT.md | 4 +- .../qiskit.circuit.library.QuadraticForm.md | 4 +- .../qiskit.circuit.library.QuantumVolume.md | 4 +- .../dev/qiskit.circuit.library.RC3XGate.md | 2 +- .../dev/qiskit.circuit.library.RCCXGate.md | 2 +- .../qiskit.circuit.library.RGQFTMultiplier.md | 4 +- .../dev/qiskit.circuit.library.RGate.md | 2 +- .../dev/qiskit.circuit.library.RVGate.md | 2 +- .../dev/qiskit.circuit.library.RXGate.md | 2 +- .../dev/qiskit.circuit.library.RXXGate.md | 2 +- .../dev/qiskit.circuit.library.RYGate.md | 2 +- .../dev/qiskit.circuit.library.RYYGate.md | 2 +- .../dev/qiskit.circuit.library.RZGate.md | 2 +- .../dev/qiskit.circuit.library.RZXGate.md | 2 +- .../dev/qiskit.circuit.library.RZZGate.md | 2 +- .../qiskit.circuit.library.RealAmplitudes.md | 4 +- .../dev/qiskit.circuit.library.Reset.md | 2 +- .../dev/qiskit.circuit.library.SGate.md | 2 +- .../dev/qiskit.circuit.library.SXGate.md | 2 +- .../dev/qiskit.circuit.library.SXdgGate.md | 2 +- .../dev/qiskit.circuit.library.SdgGate.md | 2 +- ...qiskit.circuit.library.StatePreparation.md | 2 +- .../dev/qiskit.circuit.library.SwapGate.md | 2 +- .../dev/qiskit.circuit.library.TGate.md | 2 +- .../dev/qiskit.circuit.library.TdgGate.md | 2 +- .../dev/qiskit.circuit.library.TwoLocal.md | 6 +- .../dev/qiskit.circuit.library.U1Gate.md | 2 +- .../dev/qiskit.circuit.library.U2Gate.md | 2 +- .../dev/qiskit.circuit.library.U3Gate.md | 2 +- .../dev/qiskit.circuit.library.UCGate.md | 2 +- .../qiskit.circuit.library.UCPauliRotGate.md | 2 +- .../dev/qiskit.circuit.library.UCRXGate.md | 2 +- .../dev/qiskit.circuit.library.UCRYGate.md | 2 +- .../dev/qiskit.circuit.library.UCRZGate.md | 2 +- .../dev/qiskit.circuit.library.UGate.md | 2 +- .../dev/qiskit.circuit.library.UnitaryGate.md | 2 +- .../qiskit.circuit.library.UnitaryOverlap.md | 4 +- ...kit.circuit.library.VBERippleCarryAdder.md | 4 +- .../qiskit.circuit.library.WeightedAdder.md | 4 +- .../dev/qiskit.circuit.library.XGate.md | 2 +- .../qiskit/dev/qiskit.circuit.library.XOR.md | 4 +- .../qiskit.circuit.library.XXMinusYYGate.md | 2 +- .../qiskit.circuit.library.XXPlusYYGate.md | 2 +- .../dev/qiskit.circuit.library.YGate.md | 2 +- .../dev/qiskit.circuit.library.ZFeatureMap.md | 4 +- .../dev/qiskit.circuit.library.ZGate.md | 2 +- .../qiskit.circuit.library.ZZFeatureMap.md | 4 +- .../dev/qiskit.circuit.library.iSwapGate.md | 2 +- .../dev/qiskit.dagcircuit.DAGCircuit.md | 2 +- .../dev/qiskit.dagcircuit.DAGDepNode.md | 2 +- .../dev/qiskit.dagcircuit.DAGDependency.md | 2 +- .../qiskit/dev/qiskit.dagcircuit.DAGInNode.md | 2 +- .../qiskit/dev/qiskit.dagcircuit.DAGNode.md | 2 +- .../qiskit/dev/qiskit.dagcircuit.DAGOpNode.md | 2 +- .../dev/qiskit.dagcircuit.DAGOutNode.md | 2 +- .../dev/qiskit.passmanager.BaseController.md | 14 +- .../dev/qiskit.passmanager.BasePassManager.md | 2 +- ...iskit.passmanager.ConditionalController.md | 14 +- .../qiskit.passmanager.DoWhileController.md | 14 +- ...qiskit.passmanager.FlowControllerLinear.md | 14 +- .../dev/qiskit.passmanager.GenericPass.md | 10 +- .../qiskit.passmanager.PassManagerState.md | 2 +- .../dev/qiskit.passmanager.PropertySet.md | 4 +- .../dev/qiskit.passmanager.WorkflowStatus.md | 2 +- .../dev/qiskit.primitives.BackendEstimator.md | 12 +- .../dev/qiskit.primitives.BackendSampler.md | 10 +- .../dev/qiskit.primitives.BaseEstimatorV2.md | 2 +- .../dev/qiskit.primitives.BaseSamplerV2.md | 2 +- .../qiskit/dev/qiskit.primitives.Estimator.md | 4 +- .../dev/qiskit.primitives.EstimatorResult.md | 2 +- .../dev/qiskit.primitives.PrimitiveResult.md | 6 +- .../qiskit/dev/qiskit.primitives.PubResult.md | 2 +- .../qiskit/dev/qiskit.primitives.Sampler.md | 4 +- .../dev/qiskit.primitives.SamplerResult.md | 4 +- .../qiskit.primitives.StatevectorEstimator.md | 2 +- .../qiskit.primitives.StatevectorSampler.md | 2 +- .../qiskit/dev/qiskit.providers.Backend.md | 2 +- .../qiskit/dev/qiskit.providers.BackendV1.md | 2 +- .../qiskit/dev/qiskit.providers.BackendV2.md | 2 +- .../qiskit.providers.BackendV2Converter.md | 2 +- docs/api/qiskit/dev/qiskit.providers.Job.md | 2 +- .../qiskit/dev/qiskit.providers.JobStatus.md | 2 +- docs/api/qiskit/dev/qiskit.providers.JobV1.md | 2 +- .../qiskit/dev/qiskit.providers.Options.md | 2 +- .../qiskit/dev/qiskit.providers.Provider.md | 2 +- .../qiskit/dev/qiskit.providers.ProviderV1.md | 2 +- .../dev/qiskit.providers.QubitProperties.md | 2 +- ....providers.basic_provider.BasicProvider.md | 2 +- ...iders.basic_provider.BasicProviderError.md | 2 +- ...oviders.basic_provider.BasicProviderJob.md | 2 +- ...providers.basic_provider.BasicSimulator.md | 4 +- .../dev/qiskit.providers.convert_to_target.md | 2 +- ...providers.fake_provider.Fake127QPulseV1.md | 4 +- .../qiskit.providers.fake_provider.Fake1Q.md | 2 +- ...iskit.providers.fake_provider.Fake20QV1.md | 4 +- ....providers.fake_provider.Fake27QPulseV1.md | 4 +- ...qiskit.providers.fake_provider.Fake5QV1.md | 4 +- ...t.providers.fake_provider.Fake7QPulseV1.md | 4 +- ...providers.fake_provider.FakeOpenPulse2Q.md | 2 +- ...providers.fake_provider.FakeOpenPulse3Q.md | 2 +- ...roviders.fake_provider.GenericBackendV2.md | 4 +- ...t.providers.models.BackendConfiguration.md | 2 +- ...skit.providers.models.BackendProperties.md | 2 +- .../qiskit.providers.models.BackendStatus.md | 2 +- .../dev/qiskit.providers.models.Command.md | 2 +- .../dev/qiskit.providers.models.GateConfig.md | 2 +- .../qiskit.providers.models.GateProperties.md | 2 +- .../dev/qiskit.providers.models.JobStatus.md | 2 +- .../dev/qiskit.providers.models.Nduv.md | 2 +- ...viders.models.PulseBackendConfiguration.md | 2 +- .../qiskit.providers.models.PulseDefaults.md | 2 +- ...oviders.models.QasmBackendConfiguration.md | 2 +- .../dev/qiskit.providers.models.UchannelLO.md | 2 +- .../qiskit.pulse.InstructionScheduleMap.md | 2 +- docs/api/qiskit/dev/qiskit.pulse.Schedule.md | 14 +- .../qiskit/dev/qiskit.pulse.ScheduleBlock.md | 14 +- .../qiskit.pulse.channels.AcquireChannel.md | 2 +- .../qiskit.pulse.channels.ControlChannel.md | 2 +- .../dev/qiskit.pulse.channels.DriveChannel.md | 2 +- .../qiskit.pulse.channels.MeasureChannel.md | 2 +- .../dev/qiskit.pulse.channels.MemorySlot.md | 2 +- .../dev/qiskit.pulse.channels.RegisterSlot.md | 2 +- .../qiskit.pulse.channels.SnapshotChannel.md | 2 +- .../dev/qiskit.pulse.instructions.Acquire.md | 2 +- .../dev/qiskit.pulse.instructions.Delay.md | 2 +- .../dev/qiskit.pulse.instructions.Play.md | 2 +- .../qiskit.pulse.instructions.Reference.md | 2 +- ...skit.pulse.instructions.RelativeBarrier.md | 2 +- .../qiskit.pulse.instructions.SetFrequency.md | 2 +- .../dev/qiskit.pulse.instructions.SetPhase.md | 2 +- ...iskit.pulse.instructions.ShiftFrequency.md | 2 +- .../qiskit.pulse.instructions.ShiftPhase.md | 2 +- .../dev/qiskit.pulse.instructions.Snapshot.md | 2 +- .../qiskit.pulse.instructions.TimeBlockade.md | 2 +- ...qiskit.pulse.library.Constant_class.rst.md | 2 +- .../dev/qiskit.pulse.library.Cos_class.rst.md | 2 +- .../qiskit.pulse.library.Drag_class.rst.md | 2 +- .../dev/qiskit.pulse.library.GaussianDeriv.md | 2 +- .../qiskit.pulse.library.GaussianSquare.md | 2 +- ...qiskit.pulse.library.GaussianSquareDrag.md | 2 +- ...qiskit.pulse.library.Gaussian_class.rst.md | 2 +- ...qiskit.pulse.library.Sawtooth_class.rst.md | 2 +- .../dev/qiskit.pulse.library.SechDeriv.md | 2 +- .../dev/qiskit.pulse.library.Sech_fun.rst.md | 2 +- .../dev/qiskit.pulse.library.Sin_class.rst.md | 2 +- .../qiskit.pulse.library.Square_fun.rst.md | 2 +- .../dev/qiskit.pulse.library.SymbolicPulse.md | 2 +- ...qiskit.pulse.library.Triangle_class.rst.md | 2 +- .../dev/qiskit.pulse.library.Waveform.md | 2 +- ...skit.pulse.library.gaussian_square_echo.md | 2 +- ...qiskit.pulse.transforms.AlignEquispaced.md | 2 +- .../dev/qiskit.pulse.transforms.AlignFunc.md | 2 +- .../dev/qiskit.pulse.transforms.AlignLeft.md | 2 +- .../dev/qiskit.pulse.transforms.AlignRight.md | 2 +- ...qiskit.pulse.transforms.AlignSequential.md | 2 +- .../qiskit/dev/qiskit.qobj.GateCalibration.md | 2 +- .../dev/qiskit.qobj.PulseLibraryItem.md | 2 +- docs/api/qiskit/dev/qiskit.qobj.PulseQobj.md | 2 +- .../qiskit/dev/qiskit.qobj.PulseQobjConfig.md | 2 +- .../dev/qiskit.qobj.PulseQobjExperiment.md | 2 +- .../qiskit.qobj.PulseQobjExperimentConfig.md | 2 +- .../dev/qiskit.qobj.PulseQobjInstruction.md | 2 +- .../qiskit.qobj.QasmExperimentCalibrations.md | 2 +- docs/api/qiskit/dev/qiskit.qobj.QasmQobj.md | 2 +- .../qiskit/dev/qiskit.qobj.QasmQobjConfig.md | 2 +- .../dev/qiskit.qobj.QasmQobjExperiment.md | 2 +- .../qiskit.qobj.QasmQobjExperimentConfig.md | 2 +- .../dev/qiskit.qobj.QasmQobjInstruction.md | 2 +- .../dev/qiskit.qobj.QobjExperimentHeader.md | 2 +- docs/api/qiskit/dev/qiskit.qobj.QobjHeader.md | 2 +- .../dev/qiskit.qobj.QobjMeasurementOption.md | 2 +- .../dev/qiskit.quantum_info.CNOTDihedral.md | 2 +- .../api/qiskit/dev/qiskit.quantum_info.Chi.md | 2 +- .../qiskit/dev/qiskit.quantum_info.Choi.md | 2 +- .../dev/qiskit.quantum_info.Clifford.md | 2 +- .../dev/qiskit.quantum_info.DensityMatrix.md | 2 +- .../qiskit/dev/qiskit.quantum_info.Kraus.md | 2 +- .../dev/qiskit.quantum_info.Operator.md | 2 +- .../api/qiskit/dev/qiskit.quantum_info.PTM.md | 2 +- .../qiskit/dev/qiskit.quantum_info.Pauli.md | 2 +- .../dev/qiskit.quantum_info.PauliList.md | 2 +- .../dev/qiskit.quantum_info.Quaternion.md | 2 +- .../dev/qiskit.quantum_info.ScalarOp.md | 2 +- .../dev/qiskit.quantum_info.SparsePauliOp.md | 2 +- .../qiskit.quantum_info.StabilizerState.md | 2 +- .../dev/qiskit.quantum_info.Statevector.md | 2 +- .../dev/qiskit.quantum_info.Stinespring.md | 2 +- .../qiskit/dev/qiskit.quantum_info.SuperOp.md | 2 +- .../dev/qiskit.quantum_info.Z2Symmetries.md | 6 +- .../dev/qiskit.quantum_info.pauli_basis.md | 2 +- .../dev/qiskit.result.BaseReadoutMitigator.md | 2 +- ...iskit.result.CorrelatedReadoutMitigator.md | 2 +- docs/api/qiskit/dev/qiskit.result.Counts.md | 4 +- .../qiskit.result.LocalReadoutMitigator.md | 2 +- .../dev/qiskit.result.ProbDistribution.md | 4 +- .../dev/qiskit.result.QuasiDistribution.md | 4 +- docs/api/qiskit/dev/qiskit.result.Result.md | 2 +- .../qiskit/dev/qiskit.result.ResultError.md | 2 +- .../qiskit.synthesis.EvolutionSynthesis.md | 2 +- .../qiskit/dev/qiskit.synthesis.LieTrotter.md | 2 +- .../dev/qiskit.synthesis.MatrixExponential.md | 2 +- ...iskit.synthesis.OneQubitEulerDecomposer.md | 2 +- .../dev/qiskit.synthesis.ProductFormula.md | 2 +- .../api/qiskit/dev/qiskit.synthesis.QDrift.md | 2 +- ...it.synthesis.SolovayKitaevDecomposition.md | 2 +- .../dev/qiskit.synthesis.SuzukiTrotter.md | 2 +- ...iskit.synthesis.TwoQubitBasisDecomposer.md | 2 +- ...kit.synthesis.TwoQubitWeylDecomposition.md | 4 +- .../dev/qiskit.synthesis.XXDecomposer.md | 2 +- .../dev/qiskit.synthesis.unitary.aqc.AQC.md | 2 +- ...ynthesis.unitary.aqc.ApproximateCircuit.md | 2 +- ...esis.unitary.aqc.ApproximatingObjective.md | 2 +- ...t.synthesis.unitary.aqc.CNOTUnitCircuit.md | 2 +- ...synthesis.unitary.aqc.CNOTUnitObjective.md | 2 +- ...is.unitary.aqc.DefaultCNOTUnitObjective.md | 2 +- ...hesis.unitary.aqc.FastCNOTUnitObjective.md | 2 +- .../dev/qiskit.transpiler.AnalysisPass.md | 10 +- .../dev/qiskit.transpiler.CouplingMap.md | 2 +- .../qiskit.transpiler.InstructionDurations.md | 2 +- ...qiskit.transpiler.InstructionProperties.md | 2 +- .../qiskit/dev/qiskit.transpiler.Layout.md | 2 +- .../dev/qiskit.transpiler.PassManager.md | 2 +- .../qiskit.transpiler.PassManagerConfig.md | 2 +- .../qiskit.transpiler.StagedPassManager.md | 2 +- .../qiskit/dev/qiskit.transpiler.Target.md | 2 +- .../qiskit.transpiler.TransformationPass.md | 10 +- .../dev/qiskit.transpiler.TranspileLayout.md | 2 +- .../qiskit.transpiler.passes.ALAPSchedule.md | 10 +- ....transpiler.passes.ALAPScheduleAnalysis.md | 10 +- ...it.transpiler.passes.AQCSynthesisPlugin.md | 2 +- .../qiskit.transpiler.passes.ASAPSchedule.md | 10 +- ....transpiler.passes.ASAPScheduleAnalysis.md | 10 +- .../qiskit.transpiler.passes.AlignMeasures.md | 10 +- .../qiskit.transpiler.passes.ApplyLayout.md | 10 +- ...r.passes.BarrierBeforeFinalMeasurements.md | 10 +- .../dev/qiskit.transpiler.passes.BasicSwap.md | 10 +- ...iskit.transpiler.passes.BasisTranslator.md | 10 +- .../dev/qiskit.transpiler.passes.CSPLayout.md | 10 +- ...qiskit.transpiler.passes.CXCancellation.md | 10 +- ...it.transpiler.passes.CheckGateDirection.md | 10 +- .../dev/qiskit.transpiler.passes.CheckMap.md | 10 +- .../qiskit.transpiler.passes.Collect1qRuns.md | 10 +- ...iskit.transpiler.passes.Collect2qBlocks.md | 10 +- ...skit.transpiler.passes.CollectCliffords.md | 10 +- ...ranspiler.passes.CollectLinearFunctions.md | 10 +- ...t.transpiler.passes.CollectMultiQBlocks.md | 10 +- ...t.transpiler.passes.CommutationAnalysis.md | 10 +- ...anspiler.passes.CommutativeCancellation.md | 10 +- ...r.passes.CommutativeInverseCancellation.md | 10 +- ...transpiler.passes.Commuting2qGateRouter.md | 10 +- ...kit.transpiler.passes.ConsolidateBlocks.md | 10 +- ...transpiler.passes.ConstrainedReschedule.md | 10 +- ...t.transpiler.passes.ContainsInstruction.md | 10 +- ...nspiler.passes.ConvertConditionsToIfOps.md | 10 +- .../dev/qiskit.transpiler.passes.CountOps.md | 10 +- ...t.transpiler.passes.CountOpsLongestPath.md | 10 +- .../qiskit.transpiler.passes.DAGFixedPoint.md | 10 +- ...qiskit.transpiler.passes.DAGLongestPath.md | 10 +- .../dev/qiskit.transpiler.passes.Decompose.md | 10 +- .../qiskit.transpiler.passes.DenseLayout.md | 10 +- .../dev/qiskit.transpiler.passes.Depth.md | 10 +- ...t.transpiler.passes.DynamicalDecoupling.md | 10 +- ...nspiler.passes.EchoRZXWeylDecomposition.md | 10 +- ...it.transpiler.passes.EnlargeWithAncilla.md | 10 +- .../qiskit.transpiler.passes.FilterOpNodes.md | 10 +- .../qiskit.transpiler.passes.FixedPoint.md | 10 +- ...transpiler.passes.FullAncillaAllocation.md | 10 +- .../qiskit.transpiler.passes.GateDirection.md | 10 +- .../qiskit.transpiler.passes.GatesInBasis.md | 10 +- .../dev/qiskit.transpiler.passes.HLSConfig.md | 2 +- ...it.transpiler.passes.HighLevelSynthesis.md | 10 +- ...qiskit.transpiler.passes.HoareOptimizer.md | 10 +- ...nspiler.passes.InstructionDurationCheck.md | 10 +- ...t.transpiler.passes.InverseCancellation.md | 10 +- ...skit.transpiler.passes.Layout2qDistance.md | 10 +- ...er.passes.LinearFunctionsToPermutations.md | 10 +- .../qiskit.transpiler.passes.LookaheadSwap.md | 10 +- ...transpiler.passes.MergeAdjacentBarriers.md | 10 +- .../qiskit.transpiler.passes.MinimumPoint.md | 10 +- ...skit.transpiler.passes.NormalizeRXAngle.md | 10 +- ...skit.transpiler.passes.NumTensorFactors.md | 10 +- ...iskit.transpiler.passes.Optimize1qGates.md | 10 +- ...ler.passes.Optimize1qGatesDecomposition.md | 10 +- ...passes.Optimize1qGatesSimpleCommutation.md | 10 +- ...kit.transpiler.passes.OptimizeAnnotated.md | 10 +- ...kit.transpiler.passes.OptimizeCliffords.md | 10 +- .../dev/qiskit.transpiler.passes.PadDelay.md | 10 +- ...ranspiler.passes.PadDynamicalDecoupling.md | 10 +- .../qiskit.transpiler.passes.PulseGates.md | 10 +- ....transpiler.passes.RXCalibrationBuilder.md | 10 +- ...transpiler.passes.RZXCalibrationBuilder.md | 10 +- ...iler.passes.RZXCalibrationBuilderNoEcho.md | 10 +- ...qiskit.transpiler.passes.RemoveBarriers.md | 10 +- ...passes.RemoveDiagonalGatesBeforeMeasure.md | 10 +- ...anspiler.passes.RemoveFinalMeasurements.md | 10 +- ...ranspiler.passes.RemoveResetInZeroState.md | 10 +- ....passes.ResetAfterMeasureSimplification.md | 10 +- .../qiskit.transpiler.passes.SabreLayout.md | 10 +- ...qiskit.transpiler.passes.SabrePreLayout.md | 10 +- .../dev/qiskit.transpiler.passes.SabreSwap.md | 10 +- .../qiskit.transpiler.passes.SetIOLatency.md | 10 +- .../dev/qiskit.transpiler.passes.SetLayout.md | 10 +- .../dev/qiskit.transpiler.passes.Size.md | 10 +- .../qiskit.transpiler.passes.SolovayKitaev.md | 10 +- ...ranspiler.passes.SolovayKitaevSynthesis.md | 2 +- ...qiskit.transpiler.passes.StochasticSwap.md | 10 +- ....transpiler.passes.TemplateOptimization.md | 10 +- ...it.transpiler.passes.TimeUnitConversion.md | 10 +- ...iler.passes.TranslateParameterizedGates.md | 10 +- .../qiskit.transpiler.passes.TrivialLayout.md | 10 +- ...skit.transpiler.passes.UnitarySynthesis.md | 10 +- ...qiskit.transpiler.passes.Unroll3qOrMore.md | 10 +- ...anspiler.passes.UnrollCustomDefinitions.md | 10 +- ...qiskit.transpiler.passes.UnrollForLoops.md | 10 +- .../dev/qiskit.transpiler.passes.VF2Layout.md | 10 +- .../qiskit.transpiler.passes.VF2PostLayout.md | 10 +- ...it.transpiler.passes.ValidatePulseGates.md | 10 +- .../dev/qiskit.transpiler.passes.Width.md | 10 +- ...nthesis.plugin.HighLevelSynthesisPlugin.md | 2 +- ....plugin.HighLevelSynthesisPluginManager.md | 2 +- ...synthesis.plugin.UnitarySynthesisPlugin.md | 2 +- ...is.plugin.UnitarySynthesisPluginManager.md | 2 +- ...lugin.high_level_synthesis_plugin_names.md | 2 +- ...s.plugin.unitary_synthesis_plugin_names.md | 2 +- ...smanagers.plugin.PassManagerStagePlugin.md | 2 +- ...rs.plugin.PassManagerStagePluginManager.md | 2 +- .../qiskit.visualization.array_to_latex.md | 2 +- .../qiskit.visualization.circuit_drawer.md | 2 +- .../dev/qiskit.visualization.dag_drawer.md | 2 +- ...iskit.visualization.pass_manager_drawer.md | 2 +- ...it.visualization.plot_bloch_multivector.md | 2 +- .../qiskit.visualization.plot_bloch_vector.md | 2 +- ...iskit.visualization.plot_circuit_layout.md | 2 +- .../qiskit.visualization.plot_coupling_map.md | 2 +- .../qiskit.visualization.plot_distribution.md | 2 +- .../qiskit.visualization.plot_error_map.md | 2 +- .../dev/qiskit.visualization.plot_gate_map.md | 2 +- .../qiskit.visualization.plot_histogram.md | 2 +- .../qiskit.visualization.plot_state_city.md | 2 +- .../qiskit.visualization.plot_state_hinton.md | 2 +- ...iskit.visualization.plot_state_paulivec.md | 2 +- ...qiskit.visualization.plot_state_qsphere.md | 2 +- ...skit.visualization.visualize_transition.md | 2 +- docs/api/qiskit/dev/qpy.md | 8 +- docs/api/qiskit/dev/quantum_info.md | 54 +++---- docs/api/qiskit/dev/result.md | 8 +- docs/api/qiskit/dev/scheduler.md | 8 +- docs/api/qiskit/dev/synthesis.md | 46 +++--- docs/api/qiskit/dev/synthesis_aqc.md | 2 +- docs/api/qiskit/dev/transpiler.md | 12 +- docs/api/qiskit/dev/transpiler_passes.md | 2 +- docs/api/qiskit/dev/transpiler_plugins.md | 4 +- docs/api/qiskit/dev/transpiler_preset.md | 26 ++-- docs/api/qiskit/dev/utils.md | 28 ++-- docs/api/qiskit/dev/visualization.md | 2 +- public/api/qiskit/dev/objects.inv | Bin 66922 -> 66922 bytes public/images/api/qiskit/dev/circuit-1.png | Bin 5373 -> 5373 bytes public/images/api/qiskit/dev/circuit-2.png | Bin 3876 -> 3876 bytes public/images/api/qiskit/dev/circuit-3.png | Bin 5607 -> 5607 bytes public/images/api/qiskit/dev/circuit-4.png | Bin 29666 -> 29666 bytes public/images/api/qiskit/dev/circuit-5.png | Bin 9082 -> 7744 bytes .../api/qiskit/dev/circuit_library-1.png | Bin 6289 -> 6289 bytes public/images/api/qiskit/dev/converters-1.png | Bin 8320 -> 8320 bytes .../dev/providers_fake_provider-1_00.png | Bin 13102 -> 13102 bytes .../dev/providers_fake_provider-1_01.png | Bin 22602 -> 22602 bytes .../dev/providers_fake_provider-1_02.png | Bin 13803 -> 14352 bytes public/images/api/qiskit/dev/pulse-1.png | Bin 31312 -> 31312 bytes public/images/api/qiskit/dev/pulse-2.png | Bin 10554 -> 10893 bytes public/images/api/qiskit/dev/pulse-3.png | Bin 59471 -> 59592 bytes public/images/api/qiskit/dev/pulse-4.png | Bin 19154 -> 18992 bytes public/images/api/qiskit/dev/pulse-5.png | Bin 16234 -> 16489 bytes public/images/api/qiskit/dev/pulse-6.png | Bin 11217 -> 11536 bytes public/images/api/qiskit/dev/pulse-7.png | Bin 14079 -> 14059 bytes public/images/api/qiskit/dev/qasm3-1.png | Bin 25489 -> 25489 bytes .../dev/qiskit-circuit-ControlledGate-1.png | Bin 6414 -> 4578 bytes .../dev/qiskit-circuit-ControlledGate-2.png | Bin 7140 -> 7288 bytes .../dev/qiskit-circuit-InstructionSet-1.png | Bin 9160 -> 8936 bytes .../qiskit/dev/qiskit-circuit-Operation-1.png | Bin 5879 -> 5879 bytes .../dev/qiskit-circuit-Parameter-1_00.png | Bin 1689 -> 1689 bytes .../dev/qiskit-circuit-Parameter-1_01.png | Bin 5370 -> 5370 bytes .../dev/qiskit-circuit-QuantumCircuit-1.png | Bin 6885 -> 6885 bytes .../dev/qiskit-circuit-QuantumCircuit-2.png | Bin 16553 -> 16553 bytes .../qiskit-circuit-QuantumCircuit-3_00.png | Bin 3661 -> 3661 bytes .../qiskit-circuit-QuantumCircuit-3_01.png | Bin 3635 -> 3635 bytes .../qiskit-circuit-QuantumCircuit-4_00.png | Bin 3585 -> 3585 bytes .../qiskit-circuit-QuantumCircuit-4_01.png | Bin 3913 -> 3913 bytes .../dev/qiskit-circuit-QuantumCircuit-5.png | Bin 3214 -> 3214 bytes .../dev/qiskit-circuit-QuantumCircuit-6.png | Bin 4256 -> 4256 bytes .../dev/qiskit-circuit-library-AND-1.png | Bin 16860 -> 16860 bytes .../dev/qiskit-circuit-library-AND-2.png | Bin 17615 -> 17615 bytes ...skit-circuit-library-FourierChecking-1.png | Bin 11434 -> 11434 bytes .../dev/qiskit-circuit-library-GMS-1.png | Bin 13316 -> 13316 bytes .../dev/qiskit-circuit-library-GR-1.png | Bin 16936 -> 16936 bytes .../dev/qiskit-circuit-library-GRX-1.png | Bin 16876 -> 16876 bytes .../dev/qiskit-circuit-library-GRY-1.png | Bin 16936 -> 16936 bytes .../dev/qiskit-circuit-library-GRZ-1.png | Bin 12094 -> 12094 bytes .../qiskit-circuit-library-GraphState-1.png | Bin 15678 -> 15678 bytes ...circuit-library-HiddenLinearFunction-1.png | Bin 13076 -> 13076 bytes .../dev/qiskit-circuit-library-IQP-1.png | Bin 6597 -> 6597 bytes .../dev/qiskit-circuit-library-IQP-2.png | Bin 15203 -> 15203 bytes .../qiskit-circuit-library-InnerProduct-1.png | Bin 14234 -> 14234 bytes .../qiskit-circuit-library-MCMTVChain-1.png | Bin 14771 -> 14771 bytes .../dev/qiskit-circuit-library-OR-1.png | Bin 20577 -> 20577 bytes .../dev/qiskit-circuit-library-OR-2.png | Bin 18664 -> 18664 bytes ...iskit-circuit-library-PauliTwoDesign-1.png | Bin 10538 -> 10538 bytes .../qiskit-circuit-library-Permutation-1.png | Bin 9030 -> 9030 bytes .../qiskit-circuit-library-Permutation-2.png | Bin 16568 -> 16568 bytes ...skit-circuit-library-PermutationGate-1.png | Bin 7616 -> 7616 bytes ...skit-circuit-library-PermutationGate-2.png | Bin 16063 -> 16239 bytes ...skit-circuit-library-PhaseEstimation-1.png | Bin 12213 -> 12208 bytes ...t-circuit-library-PiecewiseChebyshev-1.png | Bin 7636 -> 7636 bytes .../dev/qiskit-circuit-library-QFT-1.png | Bin 11836 -> 11836 bytes .../dev/qiskit-circuit-library-QFT-2.png | Bin 12001 -> 12001 bytes .../dev/qiskit-circuit-library-QFT-3.png | Bin 12100 -> 12100 bytes ...qiskit-circuit-library-QuantumVolume-1.png | Bin 9389 -> 9389 bytes ...qiskit-circuit-library-QuantumVolume-2.png | Bin 19359 -> 18255 bytes .../dev/qiskit-circuit-library-XOR-1.png | Bin 12259 -> 12259 bytes .../qiskit-pulse-library-SymbolicPulse-1.png | Bin 11401 -> 11401 bytes .../dev/qiskit-quantum_info-Statevector-1.png | Bin 7558 -> 7558 bytes ...spiler-passes-DynamicalDecoupling-1_00.png | Bin 22803 -> 22803 bytes ...spiler-passes-DynamicalDecoupling-1_01.png | Bin 23583 -> 23583 bytes ...skit-transpiler-passes-FilterOpNodes-1.png | Bin 1637 -> 1637 bytes ...ler-passes-PadDynamicalDecoupling-1_00.png | Bin 22803 -> 22803 bytes ...ler-passes-PadDynamicalDecoupling-1_01.png | Bin 23583 -> 23583 bytes ...kit-transpiler-passes-RemoveBarriers-1.png | Bin 1593 -> 1593 bytes .../qiskit-visualization-circuit_drawer-1.png | Bin 3214 -> 3214 bytes ...visualization-plot_bloch_multivector-1.png | Bin 92847 -> 92847 bytes ...visualization-plot_bloch_multivector-2.png | Bin 95603 -> 95603 bytes ...skit-visualization-plot_bloch_vector-1.png | Bin 73448 -> 73448 bytes ...skit-visualization-plot_bloch_vector-2.png | Bin 74554 -> 74554 bytes ...it-visualization-plot_circuit_layout-1.png | Bin 10055 -> 10561 bytes ...skit-visualization-plot_coupling_map-1.png | Bin 8007 -> 8007 bytes ...t-visualization-plot_distribution-1_00.png | Bin 16020 -> 16020 bytes ...t-visualization-plot_distribution-1_01.png | Bin 20219 -> 20219 bytes ...t-visualization-plot_distribution-1_02.png | Bin 20276 -> 20276 bytes .../qiskit-visualization-plot_error_map-1.png | Bin 48739 -> 49098 bytes .../qiskit-visualization-plot_gate_map-1.png | Bin 8595 -> 8595 bytes ...skit-visualization-plot_histogram-1_00.png | Bin 12434 -> 12434 bytes ...skit-visualization-plot_histogram-1_01.png | Bin 16199 -> 16199 bytes ...skit-visualization-plot_histogram-1_02.png | Bin 16249 -> 16249 bytes ...qiskit-visualization-plot_state_city-1.png | Bin 117342 -> 117324 bytes ...qiskit-visualization-plot_state_city-2.png | Bin 159837 -> 159875 bytes ...skit-visualization-plot_state_hinton-1.png | Bin 11116 -> 11116 bytes ...it-visualization-plot_state_paulivec-1.png | Bin 17337 -> 17337 bytes ...it-visualization-plot_state_paulivec-2.png | Bin 18522 -> 18522 bytes ...kit-visualization-plot_state_qsphere-1.png | Bin 33861 -> 33861 bytes ...kit-visualization-plot_state_qsphere-2.png | Bin 38572 -> 38572 bytes ...qiskit-visualization-timeline_drawer-1.png | Bin 15394 -> 15729 bytes ...qiskit-visualization-timeline_drawer-2.png | Bin 8247 -> 8705 bytes ...qiskit-visualization-timeline_drawer-3.png | Bin 28165 -> 26603 bytes .../images/api/qiskit/dev/transpiler-10.png | Bin 7231 -> 7231 bytes .../images/api/qiskit/dev/transpiler-11.png | Bin 36154 -> 36154 bytes .../images/api/qiskit/dev/transpiler-12.png | Bin 9016 -> 9016 bytes .../images/api/qiskit/dev/transpiler-13.png | Bin 36154 -> 36154 bytes .../images/api/qiskit/dev/transpiler-14.png | Bin 20314 -> 20314 bytes .../images/api/qiskit/dev/transpiler-15.png | Bin 9699 -> 9699 bytes .../images/api/qiskit/dev/transpiler-16.png | Bin 24728 -> 24934 bytes .../images/api/qiskit/dev/transpiler-17.png | Bin 19234 -> 18832 bytes public/images/api/qiskit/dev/transpiler-4.png | Bin 6289 -> 6289 bytes public/images/api/qiskit/dev/transpiler-5.png | Bin 20199 -> 20199 bytes public/images/api/qiskit/dev/transpiler-6.png | Bin 10473 -> 10473 bytes public/images/api/qiskit/dev/transpiler-7.png | Bin 12152 -> 12152 bytes public/images/api/qiskit/dev/transpiler-8.png | Bin 7725 -> 7725 bytes public/images/api/qiskit/dev/transpiler-9.png | Bin 7662 -> 7662 bytes .../images/api/qiskit/dev/visualization-1.png | Bin 10426 -> 10426 bytes .../images/api/qiskit/dev/visualization-2.png | Bin 17293 -> 17293 bytes .../images/api/qiskit/dev/visualization-3.png | Bin 10033 -> 10033 bytes .../images/api/qiskit/dev/visualization-4.png | Bin 108745 -> 108756 bytes .../images/api/qiskit/dev/visualization-5.png | Bin 113145 -> 113083 bytes .../images/api/qiskit/dev/visualization-6.png | Bin 113145 -> 113083 bytes scripts/api-html-artifacts.json | 3 +- 598 files changed, 1274 insertions(+), 1273 deletions(-) diff --git a/docs/api/qiskit/dev/_package.json b/docs/api/qiskit/dev/_package.json index 912908d18be..7411a89f078 100644 --- a/docs/api/qiskit/dev/_package.json +++ b/docs/api/qiskit/dev/_package.json @@ -1,4 +1,4 @@ { "name": "qiskit", - "version": "1.0.0rc1" + "version": "1.1.0-dev" } diff --git a/docs/api/qiskit/dev/assembler.md b/docs/api/qiskit/dev/assembler.md index c6add8870b5..3edc543c3ca 100644 --- a/docs/api/qiskit/dev/assembler.md +++ b/docs/api/qiskit/dev/assembler.md @@ -24,7 +24,7 @@ python_api_name: qiskit.assembler -`qiskit.assembler.assemble_circuits(circuits, run_config, qobj_id, qobj_header)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/assembler/assemble_circuits.py "view source code") +`qiskit.assembler.assemble_circuits(circuits, run_config, qobj_id, qobj_header)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/assembler/assemble_circuits.py "view source code") Assembles a list of circuits into a qobj that can be run on the backend. @@ -69,7 +69,7 @@ qobj = assemble_circuits(circuits=[qc], -`qiskit.assembler.assemble_schedules(schedules, qobj_id, qobj_header, run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/assembler/assemble_schedules.py "view source code") +`qiskit.assembler.assemble_schedules(schedules, qobj_id, qobj_header, run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/assembler/assemble_schedules.py "view source code") Assembles a list of schedules into a qobj that can be run on the backend. @@ -135,7 +135,7 @@ pulseQobj = assemble_schedules(schedules=[schedule], -`qiskit.assembler.disassemble(qobj)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/assembler/disassemble.py "view source code") +`qiskit.assembler.disassemble(qobj)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/assembler/disassemble.py "view source code") Disassemble a qobj and return the circuits or pulse schedules, run\_config, and user header. diff --git a/docs/api/qiskit/dev/circuit.md b/docs/api/qiskit/dev/circuit.md index fcb3cece038..5f5b6b27810 100644 --- a/docs/api/qiskit/dev/circuit.md +++ b/docs/api/qiskit/dev/circuit.md @@ -289,7 +289,7 @@ with qc.switch(cr) as case: -`qiskit.circuit.random.random_circuit(num_qubits, depth, max_operands=4, measure=False, conditional=False, reset=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/random/utils.py "view source code") +`qiskit.circuit.random.random_circuit(num_qubits, depth, max_operands=4, measure=False, conditional=False, reset=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/random/utils.py "view source code") Generate random circuit of arbitrary size and form. @@ -334,7 +334,7 @@ Almost all circuit functions and methods will raise a [`CircuitError`](#qiskit.c -`qiskit.circuit.CircuitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/exceptions.py "view source code") +`qiskit.circuit.CircuitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/exceptions.py "view source code") Base class for errors raised while processing a circuit. diff --git a/docs/api/qiskit/dev/circuit_classical.md b/docs/api/qiskit/dev/circuit_classical.md index 76c2915baa0..8cd8a8f518f 100644 --- a/docs/api/qiskit/dev/circuit_classical.md +++ b/docs/api/qiskit/dev/circuit_classical.md @@ -50,7 +50,7 @@ The expression system is based on tree representation. All nodes in the tree are -`qiskit.circuit.classical.expr.Expr`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/expr.py "view source code") +`qiskit.circuit.classical.expr.Expr`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/expr.py "view source code") Root base class of all nodes in the expression tree. The base case should never be instantiated directly. @@ -64,7 +64,7 @@ The entry point from general circuit objects to the expression system is by wrap -`final class qiskit.circuit.classical.expr.Var(var, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/expr.py "view source code") +`final class qiskit.circuit.classical.expr.Var(var, type)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/expr.py "view source code") A classical variable. @@ -74,7 +74,7 @@ Similarly, literals used in comparison (such as integers) should be lifted to [` -`final class qiskit.circuit.classical.expr.Value(value, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/expr.py "view source code") +`final class qiskit.circuit.classical.expr.Value(value, type)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/expr.py "view source code") A single scalar value. @@ -82,7 +82,7 @@ The operations traditionally associated with pre-, post- or infix operators in p -`final class qiskit.circuit.classical.expr.Unary(op, operand, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/expr.py "view source code") +`final class qiskit.circuit.classical.expr.Unary(op, operand, type)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/expr.py "view source code") A unary expression. @@ -120,7 +120,7 @@ Logical negation. `!operand`. -`final class qiskit.circuit.classical.expr.Binary(op, left, right, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/expr.py "view source code") +`final class qiskit.circuit.classical.expr.Binary(op, left, right, type)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/expr.py "view source code") A binary expression. @@ -237,7 +237,7 @@ Expressions in this system are defined to act only on certain sets of types. How -`final class qiskit.circuit.classical.expr.Cast(operand, type, implicit=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/expr.py "view source code") +`final class qiskit.circuit.classical.expr.Cast(operand, type, implicit=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/expr.py "view source code") A cast from one type to another, implied by the use of an expression in a different context. @@ -253,7 +253,7 @@ The functions and methods described in this section are a more user-friendly way -`qiskit.circuit.classical.expr.lift(value, /, type=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.lift(value, /, type=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Lift the given Python `value` to a [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.expr.Value") or [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var"). @@ -293,7 +293,7 @@ You can manually specify casts in cases where the cast is allowed in explicit fo -`qiskit.circuit.classical.expr.cast(operand, type, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.cast(operand, type, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create an explicit cast from the given value to the given type. @@ -318,7 +318,7 @@ There are helper constructor functions for each of the unary operations. -`qiskit.circuit.classical.expr.bit_not(operand, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.bit_not(operand, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a bitwise ‘not’ expression node from the given value, resolving any implicit casts and lifting the value into a [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") node if required. @@ -341,7 +341,7 @@ Unary(Unary.Op.BIT_NOT, Var(ClassicalRegister(3, 'c'), Uint(3)), Uint(3)) -`qiskit.circuit.classical.expr.logic_not(operand, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.logic_not(operand, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a logical ‘not’ expression node from the given value, resolving any implicit casts and lifting the value into a [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") node if required. @@ -366,7 +366,7 @@ Similarly, the binary operations and relations have helper functions defined. -`qiskit.circuit.classical.expr.bit_and(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.bit_and(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a bitwise ‘and’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -389,7 +389,7 @@ Binary(Binary.Op.BIT_AND, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(7, Uint -`qiskit.circuit.classical.expr.bit_or(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.bit_or(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a bitwise ‘or’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -412,7 +412,7 @@ Binary(Binary.Op.BIT_OR, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(5, Uint( -`qiskit.circuit.classical.expr.bit_xor(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.bit_xor(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a bitwise ‘exclusive or’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -435,7 +435,7 @@ Binary(Binary.Op.BIT_XOR, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(5, Uint -`qiskit.circuit.classical.expr.logic_and(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.logic_and(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a logical ‘and’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -458,7 +458,7 @@ Binary(Binary.Op.LOGIC_AND, Var(, Bool()), Var(, Bool()), Bool -`qiskit.circuit.classical.expr.logic_or(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.logic_or(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a logical ‘or’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -481,7 +481,7 @@ Binary(Binary.Op.LOGIC_OR, Var(, Bool()), Var(, Bool()), Bool( -`qiskit.circuit.classical.expr.equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create an ‘equal’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -504,7 +504,7 @@ Binary(Binary.Op.EQUAL, Var(ClassicalRegister(3, "c"), Uint(3)), Value(7, Uint(3 -`qiskit.circuit.classical.expr.not_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.not_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a ‘not equal’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -527,7 +527,7 @@ Binary(Binary.Op.NOT_EQUAL, Var(ClassicalRegister(3, "c"), Uint(3)), Value(7, Ui -`qiskit.circuit.classical.expr.less(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.less(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a ‘less than’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -550,7 +550,7 @@ Binary(Binary.Op.LESS, Var(ClassicalRegister(3, "c"), Uint(3)), Value(5, Uint(3) -`qiskit.circuit.classical.expr.less_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.less_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a ‘less than or equal to’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -573,7 +573,7 @@ Binary(Binary.Op.LESS_EQUAL, Var(ClassicalRegister(3, "a"), Uint(3)), Var(Classi -`qiskit.circuit.classical.expr.greater(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.greater(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a ‘greater than’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -596,7 +596,7 @@ Binary(Binary.Op.GREATER, Var(ClassicalRegister(3, "c"), Uint(3)), Value(5, Uint -`qiskit.circuit.classical.expr.greater_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.greater_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Create a ‘greater than or equal to’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. @@ -621,7 +621,7 @@ Qiskit’s legacy method for specifying equality conditions for use in condition -`qiskit.circuit.classical.expr.lift_legacy_condition(condition, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/constructors.py "view source code") +`qiskit.circuit.classical.expr.lift_legacy_condition(condition, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/constructors.py "view source code") Lift a legacy two-tuple equality condition into a new-style [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr"). @@ -650,7 +650,7 @@ A typical consumer of the expression tree wants to recursively walk through the -`qiskit.circuit.classical.expr.ExprVisitor(*args, **kwds)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/visitors.py "view source code") +`qiskit.circuit.classical.expr.ExprVisitor`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/visitors.py "view source code") Base class for visitors to the [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") tree. Subclasses should override whichever of the `visit_*` methods that they are able to handle, and should be organised such that non-existent methods will never be called. @@ -722,7 +722,7 @@ For the convenience of simple visitors that only need to inspect the variables i -`qiskit.circuit.classical.expr.iter_vars(node)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/visitors.py "view source code") +`qiskit.circuit.classical.expr.iter_vars(node)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/visitors.py "view source code") Get an iterator over the [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var") nodes referenced at any level in the given [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr"). @@ -752,7 +752,7 @@ Two expressions can be compared for direct structural equality by using the buil -`qiskit.circuit.classical.expr.structurally_equivalent(left, right, left_var_key=None, right_var_key=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/expr/visitors.py "view source code") +`qiskit.circuit.classical.expr.structurally_equivalent(left, right, left_var_key=None, right_var_key=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/expr/visitors.py "view source code") Do these two expressions have exactly the same tree structure, up to some key function for the [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var") objects? @@ -815,7 +815,7 @@ All types inherit from an abstract base class: -`qiskit.circuit.classical.types.Type`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/types.py "view source code") +`qiskit.circuit.classical.types.Type`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/types.py "view source code") Root base class of all nodes in the type tree. The base case should never be instantiated directly. @@ -827,13 +827,13 @@ The two different types available are for Booleans (corresponding to [`Clbit`](q -`final class qiskit.circuit.classical.types.Bool`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/types.py "view source code") +`final class qiskit.circuit.classical.types.Bool`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/types.py "view source code") The Boolean type. This has exactly two values: `True` and `False`. -`final class qiskit.circuit.classical.types.Uint(width)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/types.py "view source code") +`final class qiskit.circuit.classical.types.Uint(width)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/types.py "view source code") An unsigned integer of fixed bit width. @@ -853,7 +853,7 @@ The low-level interface to querying the subtyping relationship is the [`order()` -`qiskit.circuit.classical.types.order(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.order(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") Get the ordering relationship between the two types as an enumeration value. @@ -882,7 +882,7 @@ The return value is an enumeration [`Ordering`](#qiskit.circuit.classical.types. -`qiskit.circuit.classical.types.Ordering(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.Ordering(value)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") Enumeration listing the possible relations between two types. Types only have a partial ordering, so it’s possible for two types to have no sub-typing relationship. @@ -894,7 +894,7 @@ Some helper methods are then defined in terms of this low-level [`order()`](#qis -`qiskit.circuit.classical.types.is_subtype(left, right, /, strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.is_subtype(left, right, /, strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") Does the relation $\text{left} \le \text{right}$ hold? If there is no ordering relation between the two types, then this returns `False`. If `strict`, then the equality is also forbidden. @@ -925,7 +925,7 @@ False -`qiskit.circuit.classical.types.is_supertype(left, right, /, strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.is_supertype(left, right, /, strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") Does the relation $\text{left} \ge \text{right}$ hold? If there is no ordering relation between the two types, then this returns `False`. If `strict`, then the equality is also forbidden. @@ -956,7 +956,7 @@ False -`qiskit.circuit.classical.types.greater(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.greater(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") Get the greater of the two types, assuming that there is an ordering relation between them. Technically, this is a slightly restricted version of the concept of the ‘meet’ of the two types in that the return value must be one of the inputs. In practice in the type system there is no concept of a ‘sum’ type, so the ‘meet’ exists if and only if there is an ordering between the two types, and is equal to the greater of the two types. @@ -990,7 +990,7 @@ It is common to need to cast values of one type to another type. The casting rul -`qiskit.circuit.classical.types.cast_kind(from_, to_, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.cast_kind(from_, to_, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") Determine the sort of cast that is required to move from the left type to the right type. @@ -1016,7 +1016,7 @@ The return values from this function are an enumeration explaining the types of -`qiskit.circuit.classical.types.CastKind(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classical/types/ordering.py "view source code") +`qiskit.circuit.classical.types.CastKind(value)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classical/types/ordering.py "view source code") A return value indicating the type of cast that can occur from one type to another. diff --git a/docs/api/qiskit/dev/circuit_library.md b/docs/api/qiskit/dev/circuit_library.md index fe4c6347556..3032ad7ae20 100644 --- a/docs/api/qiskit/dev/circuit_library.md +++ b/docs/api/qiskit/dev/circuit_library.md @@ -328,7 +328,7 @@ Template circuits for [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.lib -`qiskit.circuit.library.templates.nct.template_nct_2a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_2a_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_2a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_2a_1.py "view source code") **Returns** @@ -342,7 +342,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_2a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_2a_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_2a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_2a_2.py "view source code") **Returns** @@ -356,7 +356,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_2a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_2a_3.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_2a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_2a_3.py "view source code") **Returns** @@ -370,7 +370,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_4a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_4a_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_4a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_4a_1.py "view source code") **Returns** @@ -384,7 +384,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_4a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_4a_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_4a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_4a_2.py "view source code") **Returns** @@ -398,7 +398,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_4a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_4a_3.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_4a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_4a_3.py "view source code") **Returns** @@ -412,7 +412,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_4b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_4b_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_4b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_4b_1.py "view source code") **Returns** @@ -426,7 +426,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_4b_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_4b_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_4b_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_4b_2.py "view source code") **Returns** @@ -440,7 +440,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_5a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_5a_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_5a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_5a_1.py "view source code") **Returns** @@ -454,7 +454,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_5a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_5a_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_5a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_5a_2.py "view source code") **Returns** @@ -468,7 +468,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_5a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_5a_3.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_5a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_5a_3.py "view source code") **Returns** @@ -482,7 +482,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_5a_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_5a_4.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_5a_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_5a_4.py "view source code") **Returns** @@ -496,7 +496,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6a_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6a_1.py "view source code") **Returns** @@ -510,7 +510,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6a_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6a_2.py "view source code") **Returns** @@ -524,7 +524,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6a_3.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6a_3.py "view source code") **Returns** @@ -538,7 +538,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6a_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6a_4.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6a_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6a_4.py "view source code") **Returns** @@ -552,7 +552,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6b_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6b_1.py "view source code") **Returns** @@ -566,7 +566,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6b_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6b_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6b_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6b_2.py "view source code") **Returns** @@ -580,7 +580,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_6c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_6c_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_6c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_6c_1.py "view source code") **Returns** @@ -594,7 +594,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_7a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_7a_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_7a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_7a_1.py "view source code") **Returns** @@ -608,7 +608,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_7b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_7b_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_7b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_7b_1.py "view source code") **Returns** @@ -622,7 +622,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_7c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_7c_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_7c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_7c_1.py "view source code") **Returns** @@ -636,7 +636,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_7d_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_7d_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_7d_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_7d_1.py "view source code") **Returns** @@ -650,7 +650,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_7e_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_7e_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_7e_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_7e_1.py "view source code") **Returns** @@ -664,7 +664,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9a_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9a_1.py "view source code") **Returns** @@ -678,7 +678,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_1.py "view source code") **Returns** @@ -692,7 +692,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_2.py "view source code") **Returns** @@ -706,7 +706,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_3.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_3.py "view source code") **Returns** @@ -720,7 +720,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_4.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_4.py "view source code") **Returns** @@ -734,7 +734,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_5()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_5.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_5()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_5.py "view source code") **Returns** @@ -748,7 +748,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_6()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_6.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_6()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_6.py "view source code") **Returns** @@ -762,7 +762,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_7()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_7.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_7()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_7.py "view source code") **Returns** @@ -776,7 +776,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_8()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_8.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_8()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_8.py "view source code") **Returns** @@ -790,7 +790,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_9()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_9.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_9()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_9.py "view source code") **Returns** @@ -804,7 +804,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_10()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_10.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_10()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_10.py "view source code") **Returns** @@ -818,7 +818,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_11()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_11.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_11()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_11.py "view source code") **Returns** @@ -832,7 +832,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9c_12()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9c_12.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9c_12()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9c_12.py "view source code") **Returns** @@ -846,7 +846,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_1.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_1.py "view source code") **Returns** @@ -860,7 +860,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_2.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_2.py "view source code") **Returns** @@ -874,7 +874,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_3.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_3.py "view source code") **Returns** @@ -888,7 +888,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_4.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_4.py "view source code") **Returns** @@ -902,7 +902,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_5()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_5.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_5()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_5.py "view source code") **Returns** @@ -916,7 +916,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_6()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_6.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_6()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_6.py "view source code") **Returns** @@ -930,7 +930,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_7()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_7.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_7()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_7.py "view source code") **Returns** @@ -944,7 +944,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_8()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_8.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_8()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_8.py "view source code") **Returns** @@ -958,7 +958,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_9()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_9.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_9()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_9.py "view source code") **Returns** @@ -972,7 +972,7 @@ template as a quantum circuit. -`qiskit.circuit.library.templates.nct.template_nct_9d_10()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/nct/template_nct_9d_10.py "view source code") +`qiskit.circuit.library.templates.nct.template_nct_9d_10()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/nct/template_nct_9d_10.py "view source code") **Returns** @@ -990,7 +990,7 @@ Template circuits over Clifford gates. -`qiskit.circuit.library.clifford_2_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_2_1.py "view source code") +`qiskit.circuit.library.clifford_2_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_2_1.py "view source code") **Returns** @@ -1004,7 +1004,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_2_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_2_2.py "view source code") +`qiskit.circuit.library.clifford_2_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_2_2.py "view source code") **Returns** @@ -1018,7 +1018,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_2_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_2_3.py "view source code") +`qiskit.circuit.library.clifford_2_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_2_3.py "view source code") **Returns** @@ -1032,7 +1032,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_2_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_2_4.py "view source code") +`qiskit.circuit.library.clifford_2_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_2_4.py "view source code") **Returns** @@ -1046,7 +1046,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_3_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_3_1.py "view source code") +`qiskit.circuit.library.clifford_3_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_3_1.py "view source code") **Returns** @@ -1060,7 +1060,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_4_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_4_1.py "view source code") +`qiskit.circuit.library.clifford_4_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_4_1.py "view source code") **Returns** @@ -1074,7 +1074,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_4_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_4_2.py "view source code") +`qiskit.circuit.library.clifford_4_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_4_2.py "view source code") **Returns** @@ -1088,7 +1088,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_4_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_4_3.py "view source code") +`qiskit.circuit.library.clifford_4_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_4_3.py "view source code") **Returns** @@ -1102,7 +1102,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_4_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_4_4.py "view source code") +`qiskit.circuit.library.clifford_4_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_4_4.py "view source code") **Returns** @@ -1116,7 +1116,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_5_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_5_1.py "view source code") +`qiskit.circuit.library.clifford_5_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_5_1.py "view source code") **Returns** @@ -1130,7 +1130,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_6_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_6_1.py "view source code") +`qiskit.circuit.library.clifford_6_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_6_1.py "view source code") **Returns** @@ -1144,7 +1144,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_6_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_6_2.py "view source code") +`qiskit.circuit.library.clifford_6_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_6_2.py "view source code") **Returns** @@ -1158,7 +1158,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_6_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_6_3.py "view source code") +`qiskit.circuit.library.clifford_6_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_6_3.py "view source code") **Returns** @@ -1172,7 +1172,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_6_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_6_4.py "view source code") +`qiskit.circuit.library.clifford_6_4()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_6_4.py "view source code") **Returns** @@ -1186,7 +1186,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_6_5()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_6_5.py "view source code") +`qiskit.circuit.library.clifford_6_5()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_6_5.py "view source code") **Returns** @@ -1200,7 +1200,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_8_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_8_1.py "view source code") +`qiskit.circuit.library.clifford_8_1()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_8_1.py "view source code") **Returns** @@ -1214,7 +1214,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_8_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_8_2.py "view source code") +`qiskit.circuit.library.clifford_8_2()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_8_2.py "view source code") **Returns** @@ -1228,7 +1228,7 @@ template as a quantum circuit. -`qiskit.circuit.library.clifford_8_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/clifford/clifford_8_3.py "view source code") +`qiskit.circuit.library.clifford_8_3()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/clifford/clifford_8_3.py "view source code") **Returns** @@ -1246,7 +1246,7 @@ Template circuits with [`RZXGate`](qiskit.circuit.library.RZXGate "qiskit.circui -`qiskit.circuit.library.rzx_yz(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/rzx/rzx_yz.py "view source code") +`qiskit.circuit.library.rzx_yz(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/rzx/rzx_yz.py "view source code") Template for CX - RYGate - CX. @@ -1254,7 +1254,7 @@ Template for CX - RYGate - CX. -`qiskit.circuit.library.rzx_xz(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/rzx/rzx_xz.py "view source code") +`qiskit.circuit.library.rzx_xz(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/rzx/rzx_xz.py "view source code") Template for CX - RXGate - CX. @@ -1262,7 +1262,7 @@ Template for CX - RXGate - CX. -`qiskit.circuit.library.rzx_cy(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/rzx/rzx_cy.py "view source code") +`qiskit.circuit.library.rzx_cy(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/rzx/rzx_cy.py "view source code") Template for CX - RYGate - CX. @@ -1270,7 +1270,7 @@ Template for CX - RYGate - CX. -`qiskit.circuit.library.rzx_zz1(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/rzx/rzx_zz1.py "view source code") +`qiskit.circuit.library.rzx_zz1(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/rzx/rzx_zz1.py "view source code") Template for CX - RZGate - CX. @@ -1278,7 +1278,7 @@ Template for CX - RZGate - CX. -`qiskit.circuit.library.rzx_zz2(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/rzx/rzx_zz2.py "view source code") +`qiskit.circuit.library.rzx_zz2(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/rzx/rzx_zz2.py "view source code") Template for CX - RZGate - CX. @@ -1286,7 +1286,7 @@ Template for CX - RZGate - CX. -`qiskit.circuit.library.rzx_zz3(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/templates/rzx/rzx_zz3.py "view source code") +`qiskit.circuit.library.rzx_zz3(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/templates/rzx/rzx_zz3.py "view source code") Template for CX - RZGate - CX. diff --git a/docs/api/qiskit/dev/circuit_singleton.md b/docs/api/qiskit/dev/circuit_singleton.md index 1af4a9086dc..db5ed51e7ad 100644 --- a/docs/api/qiskit/dev/circuit_singleton.md +++ b/docs/api/qiskit/dev/circuit_singleton.md @@ -46,7 +46,7 @@ The public classes correspond to the standard classes [`Instruction`](qiskit.cir -`qiskit.circuit.singleton.SingletonInstruction(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/singleton.py "view source code") +`qiskit.circuit.singleton.SingletonInstruction(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/singleton.py "view source code") A base class to use for [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") objects that by default are singleton instances. @@ -56,7 +56,7 @@ The exception to be aware of with this class though are the [`Instruction`](qisk -`qiskit.circuit.singleton.SingletonGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/singleton.py "view source code") +`qiskit.circuit.singleton.SingletonGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/singleton.py "view source code") A base class to use for [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") objects that by default are singleton instances. @@ -64,7 +64,7 @@ This class is very similar to [`SingletonInstruction`](#qiskit.circuit.singleton -`qiskit.circuit.singleton.SingletonControlledGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/singleton.py "view source code") +`qiskit.circuit.singleton.SingletonControlledGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/singleton.py "view source code") A base class to use for [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") objects that by default are singleton instances diff --git a/docs/api/qiskit/dev/compiler.md b/docs/api/qiskit/dev/compiler.md index 998f51e0fca..aa67f478563 100644 --- a/docs/api/qiskit/dev/compiler.md +++ b/docs/api/qiskit/dev/compiler.md @@ -24,7 +24,7 @@ python_api_name: qiskit.compiler -`qiskit.compiler.assemble(experiments, backend=None, qobj_id=None, qobj_header=None, shots=None, memory=False, seed_simulator=None, qubit_lo_freq=None, meas_lo_freq=None, qubit_lo_range=None, meas_lo_range=None, schedule_los=None, meas_level=MeasLevel.CLASSIFIED, meas_return=MeasReturnType.AVERAGE, meas_map=None, memory_slot_size=100, rep_time=None, rep_delay=None, parameter_binds=None, parametric_pulses=None, init_qubits=True, **run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/compiler/assembler.py "view source code") +`qiskit.compiler.assemble(experiments, backend=None, qobj_id=None, qobj_header=None, shots=None, memory=False, seed_simulator=None, qubit_lo_freq=None, meas_lo_freq=None, qubit_lo_range=None, meas_lo_range=None, schedule_los=None, meas_level=MeasLevel.CLASSIFIED, meas_return=MeasReturnType.AVERAGE, meas_map=None, memory_slot_size=100, rep_time=None, rep_delay=None, parameter_binds=None, parametric_pulses=None, init_qubits=True, **run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/compiler/assembler.py "view source code") Assemble a list of circuits or pulse schedules into a `Qobj`. @@ -107,7 +107,7 @@ A `Qobj` that can be run on a backend. Depending on the type of input, this will -`qiskit.compiler.schedule(circuits, backend=None, inst_map=None, meas_map=None, dt=None, method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/compiler/scheduler.py "view source code") +`qiskit.compiler.schedule(circuits, backend=None, inst_map=None, meas_map=None, dt=None, method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/compiler/scheduler.py "view source code") Schedule a circuit to a pulse `Schedule`, using the backend, according to any specified methods. Supported methods are documented in `qiskit.scheduler.schedule_circuit`. @@ -136,7 +136,7 @@ A pulse `Schedule` that implements the input circuit -`qiskit.compiler.transpile(circuits, backend=None, basis_gates=None, inst_map=None, coupling_map=None, backend_properties=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, dt=None, approximation_degree=1.0, timing_constraints=None, seed_transpiler=None, optimization_level=None, callback=None, output_name=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None, ignore_backend_supplied_default_methods=False, num_processes=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/compiler/transpiler.py "view source code") +`qiskit.compiler.transpile(circuits, backend=None, basis_gates=None, inst_map=None, coupling_map=None, backend_properties=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, dt=None, approximation_degree=1.0, timing_constraints=None, seed_transpiler=None, optimization_level=None, callback=None, output_name=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None, ignore_backend_supplied_default_methods=False, num_processes=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/compiler/transpiler.py "view source code") Transpile one or more circuits, according to some desired transpilation targets. @@ -286,7 +286,7 @@ The transpiled circuit(s). -`qiskit.compiler.sequence(scheduled_circuits, backend=None, inst_map=None, meas_map=None, dt=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/compiler/sequencer.py "view source code") +`qiskit.compiler.sequence(scheduled_circuits, backend=None, inst_map=None, meas_map=None, dt=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/compiler/sequencer.py "view source code") Schedule a scheduled circuit to a pulse `Schedule`, using the backend. diff --git a/docs/api/qiskit/dev/converters.md b/docs/api/qiskit/dev/converters.md index 9f220520dd6..d3a07f79f94 100644 --- a/docs/api/qiskit/dev/converters.md +++ b/docs/api/qiskit/dev/converters.md @@ -22,7 +22,7 @@ python_api_name: qiskit.converters -`qiskit.converters.circuit_to_dag(circuit, copy_operations=True, *, qubit_order=None, clbit_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/circuit_to_dag.py "view source code") +`qiskit.converters.circuit_to_dag(circuit, copy_operations=True, *, qubit_order=None, clbit_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/circuit_to_dag.py "view source code") Build a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). @@ -66,7 +66,7 @@ dag = circuit_to_dag(circ) -`qiskit.converters.dag_to_circuit(dag, copy_operations=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/dag_to_circuit.py "view source code") +`qiskit.converters.dag_to_circuit(dag, copy_operations=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/dag_to_circuit.py "view source code") Build a `QuantumCircuit` object from a `DAGCircuit`. @@ -110,7 +110,7 @@ circuit.draw('mpl') -`qiskit.converters.circuit_to_instruction(circuit, parameter_map=None, equivalence_library=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/circuit_to_instruction.py "view source code") +`qiskit.converters.circuit_to_instruction(circuit, parameter_map=None, equivalence_library=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/circuit_to_instruction.py "view source code") Build an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). @@ -155,7 +155,7 @@ circuit_to_instruction(circ) -`qiskit.converters.circuit_to_gate(circuit, parameter_map=None, equivalence_library=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/circuit_to_gate.py "view source code") +`qiskit.converters.circuit_to_gate(circuit, parameter_map=None, equivalence_library=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/circuit_to_gate.py "view source code") Build a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). @@ -184,7 +184,7 @@ a Gate equivalent to the action of the input circuit. Upon decomposition, this g -`qiskit.converters.dagdependency_to_circuit(dagdependency)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/dagdependency_to_circuit.py "view source code") +`qiskit.converters.dagdependency_to_circuit(dagdependency)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/dagdependency_to_circuit.py "view source code") Build a `QuantumCircuit` object from a `DAGDependency`. @@ -204,7 +204,7 @@ the circuit representing the input dag dependency. -`qiskit.converters.circuit_to_dagdependency(circuit, create_preds_and_succs=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/circuit_to_dagdependency.py "view source code") +`qiskit.converters.circuit_to_dagdependency(circuit, create_preds_and_succs=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/circuit_to_dagdependency.py "view source code") Build a `DAGDependency` object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). @@ -225,7 +225,7 @@ the DAG representing the input circuit as a dag dependency. -`qiskit.converters.dag_to_dagdependency(dag, create_preds_and_succs=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/dag_to_dagdependency.py "view source code") +`qiskit.converters.dag_to_dagdependency(dag, create_preds_and_succs=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/dag_to_dagdependency.py "view source code") Build a `DAGDependency` object from a `DAGCircuit`. @@ -246,7 +246,7 @@ the DAG representing the input circuit as a dag dependency. -`qiskit.converters.dagdependency_to_dag(dagdependency)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/converters/dagdependency_to_dag.py "view source code") +`qiskit.converters.dagdependency_to_dag(dagdependency)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/converters/dagdependency_to_dag.py "view source code") Build a `DAGCircuit` object from a `DAGDependency`. diff --git a/docs/api/qiskit/dev/dagcircuit.md b/docs/api/qiskit/dev/dagcircuit.md index 61717db6db0..c8a99cbc105 100644 --- a/docs/api/qiskit/dev/dagcircuit.md +++ b/docs/api/qiskit/dev/dagcircuit.md @@ -36,7 +36,7 @@ python_api_name: qiskit.dagcircuit -`qiskit.dagcircuit.DAGCircuitError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/exceptions.py "view source code") +`qiskit.dagcircuit.DAGCircuitError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/exceptions.py "view source code") Base class for errors raised by the DAGCircuit object. @@ -46,7 +46,7 @@ Set the error message. -`qiskit.dagcircuit.DAGDependencyError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/exceptions.py "view source code") +`qiskit.dagcircuit.DAGDependencyError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/exceptions.py "view source code") Base class for errors raised by the DAGDependency object. diff --git a/docs/api/qiskit/dev/exceptions.md b/docs/api/qiskit/dev/exceptions.md index 4f69d2fd4d5..51e8b28a7dd 100644 --- a/docs/api/qiskit/dev/exceptions.md +++ b/docs/api/qiskit/dev/exceptions.md @@ -26,7 +26,7 @@ All Qiskit-related exceptions raised by Qiskit are subclasses of the base: -`qiskit.exceptions.QiskitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.QiskitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Base class for errors raised by Qiskit. @@ -44,7 +44,7 @@ Qiskit has several optional features that depend on other packages that are not -`qiskit.exceptions.MissingOptionalLibraryError(libname, name, pip_install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.MissingOptionalLibraryError(libname, name, pip_install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Raised when an optional library is missing. @@ -56,7 +56,7 @@ Two more uncommon errors relate to failures in reading user-configuration files, -`qiskit.exceptions.QiskitUserConfigError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.QiskitUserConfigError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Raised when an error is encountered reading a user config file. @@ -66,7 +66,7 @@ Set the error message. -`qiskit.exceptions.InvalidFileError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.InvalidFileError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Raised when the file provided is not valid for the specific task. @@ -80,7 +80,7 @@ Some particular features of Qiskit may raise custom warnings. In general, Qiskit -`qiskit.exceptions.QiskitWarning`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.QiskitWarning`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Common subclass of warnings for Qiskit-specific warnings being raised. @@ -90,7 +90,7 @@ Related to [`MissingOptionalLibraryError`](#qiskit.exceptions.MissingOptionalLib -`qiskit.exceptions.OptionalDependencyImportWarning`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.OptionalDependencyImportWarning`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Raised when an optional library raises errors during its import. @@ -104,7 +104,7 @@ When experimental features are being used, Qiskit will raise [`ExperimentalWarni -`qiskit.exceptions.ExperimentalWarning`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/exceptions.py "view source code") +`qiskit.exceptions.ExperimentalWarning`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/exceptions.py "view source code") Raised when an experimental feature is being used. diff --git a/docs/api/qiskit/dev/passmanager.md b/docs/api/qiskit/dev/passmanager.md index 90864163298..e8b61dd8a3f 100644 --- a/docs/api/qiskit/dev/passmanager.md +++ b/docs/api/qiskit/dev/passmanager.md @@ -164,7 +164,7 @@ With the pass manager framework, a developer can flexibly customize the optimiza -`qiskit.passmanager.PassManagerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/exceptions.py "view source code") +`qiskit.passmanager.PassManagerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/exceptions.py "view source code") Pass manager error. diff --git a/docs/api/qiskit/dev/providers.md b/docs/api/qiskit/dev/providers.md index 3dac2d0727b..ba43fc9b098 100644 --- a/docs/api/qiskit/dev/providers.md +++ b/docs/api/qiskit/dev/providers.md @@ -79,7 +79,7 @@ It’s worth pointing out that Terra’s version support policy doesn’t mean p -`qiskit.providers.QiskitBackendNotFoundError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/exceptions.py "view source code") +`qiskit.providers.QiskitBackendNotFoundError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/exceptions.py "view source code") Base class for errors raised while looking for a backend. @@ -89,7 +89,7 @@ Set the error message. -`qiskit.providers.BackendPropertyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/exceptions.py "view source code") +`qiskit.providers.BackendPropertyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/exceptions.py "view source code") Base class for errors raised while looking for a backend property. @@ -99,7 +99,7 @@ Set the error message. -`qiskit.providers.JobError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/exceptions.py "view source code") +`qiskit.providers.JobError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/exceptions.py "view source code") Base class for errors raised by Jobs. @@ -109,7 +109,7 @@ Set the error message. -`qiskit.providers.JobTimeoutError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/exceptions.py "view source code") +`qiskit.providers.JobTimeoutError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/exceptions.py "view source code") Base class for timeout errors raised by jobs. @@ -119,7 +119,7 @@ Set the error message. -`qiskit.providers.BackendConfigurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/exceptions.py "view source code") +`qiskit.providers.BackendConfigurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/exceptions.py "view source code") Base class for errors raised by the BackendConfiguration. diff --git a/docs/api/qiskit/dev/providers_fake_provider.md b/docs/api/qiskit/dev/providers_fake_provider.md index 45b0568f3c1..9a24b64058a 100644 --- a/docs/api/qiskit/dev/providers_fake_provider.md +++ b/docs/api/qiskit/dev/providers_fake_provider.md @@ -83,7 +83,7 @@ The V1 fake backends are based on a set of base classes: -`qiskit.providers.fake_provider.FakeBackend(configuration, time_alive=10)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/fake_backend.py "view source code") +`qiskit.providers.fake_provider.FakeBackend(configuration, time_alive=10)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/fake_backend.py "view source code") This is a dummy backend just for testing purposes. @@ -96,7 +96,7 @@ FakeBackend initializer. -`qiskit.providers.fake_provider.FakeQasmBackend`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/fake_qasm_backend.py "view source code") +`qiskit.providers.fake_provider.FakeQasmBackend`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/fake_qasm_backend.py "view source code") A fake OpenQASM backend. @@ -109,7 +109,7 @@ FakeBackend initializer. -`qiskit.providers.fake_provider.FakePulseBackend`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/fake_pulse_backend.py "view source code") +`qiskit.providers.fake_provider.FakePulseBackend`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/fake_pulse_backend.py "view source code") A fake pulse backend. diff --git a/docs/api/qiskit/dev/pulse.md b/docs/api/qiskit/dev/pulse.md index 08f552de5f7..c2c681134e9 100644 --- a/docs/api/qiskit/dev/pulse.md +++ b/docs/api/qiskit/dev/pulse.md @@ -72,7 +72,7 @@ These are all instances of the same base class: -`qiskit.pulse.instructions.Instruction(operands, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/instruction.py "view source code") +`qiskit.pulse.instructions.Instruction(operands, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/instruction.py "view source code") The smallest schedulable unit: a single instruction. It has a fixed duration and specified channels. @@ -165,7 +165,7 @@ All channels are children of the same abstract base class: -`qiskit.pulse.channels.Channel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.Channel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Base class of channels. Channels provide a Qiskit-side label for typical quantum control hardware signal channels. The final label -> physical channel mapping is the responsibility of the hardware backend. For instance, `DriveChannel(0)` holds instructions which the backend should map to the signal line driving gate operations on the qubit labeled (indexed) 0. @@ -220,7 +220,7 @@ These are all subtypes of the abstract base class [`AlignmentKind`](#qiskit.puls -`qiskit.pulse.transforms.AlignmentKind(context_params)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/alignments.py "view source code") +`qiskit.pulse.transforms.AlignmentKind(context_params)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/alignments.py "view source code") An abstract class for schedule alignment. @@ -236,7 +236,7 @@ The canonicalization transforms convert schedules to a form amenable for executi -`qiskit.pulse.transforms.add_implicit_acquires(schedule, meas_map)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.add_implicit_acquires(schedule, meas_map)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Return a new schedule with implicit acquires from the measurement mapping replaced by explicit ones. @@ -246,7 +246,7 @@ Return a new schedule with implicit acquires from the measurement mapping replac **Parameters** -* **schedule** (*ScheduleComponent*) – Schedule to be aligned. +* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule to be aligned. * **meas\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – List of lists of qubits that are measured together. **Returns** @@ -255,13 +255,13 @@ A `Schedule` with the additional acquisition instructions. **Return type** -[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") ### align\_measures -`qiskit.pulse.transforms.align_measures(schedules, inst_map=None, cal_gate='u3', max_calibration_duration=None, align_time=None, align_all=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.align_measures(schedules, inst_map=None, cal_gate='u3', max_calibration_duration=None, align_time=None, align_all=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Return new schedules where measurements occur at the same physical time. @@ -330,7 +330,7 @@ The input list of schedules transformed to have their measurements aligned. -`qiskit.pulse.transforms.block_to_schedule(block)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.block_to_schedule(block)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Convert `ScheduleBlock` to `Schedule`. @@ -359,13 +359,13 @@ Scheduled pulse program. -`qiskit.pulse.transforms.compress_pulses(schedules)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.compress_pulses(schedules)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Optimization pass to replace identical pulses. **Parameters** -**schedules** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule")*]*) – Schedules to compress. +**schedules** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*qiskit.pulse.schedule.Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")*]*) – Schedules to compress. **Returns** @@ -373,13 +373,13 @@ Compressed schedules. **Return type** -[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule")] +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.pulse.schedule.Schedule](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")] ### flatten -`qiskit.pulse.transforms.flatten(program)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.flatten(program)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Flatten (inline) any called nodes into a Schedule tree with no nested children. @@ -403,7 +403,7 @@ Flatten pulse program. -`qiskit.pulse.transforms.inline_subroutines(program)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.inline_subroutines(program)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Recursively remove call instructions and inline the respective subroutine instructions. @@ -429,7 +429,7 @@ A schedule without subroutine. -`qiskit.pulse.transforms.pad(schedule, channels=None, until=None, inplace=False, pad_with=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.pad(schedule, channels=None, until=None, inplace=False, pad_with=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Pad the input Schedule with `Delay``s on all unoccupied timeslots until ``schedule.duration` or `until` if not `None`. @@ -457,7 +457,7 @@ The padded schedule. -`qiskit.pulse.transforms.remove_directives(schedule)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.remove_directives(schedule)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Remove directives. @@ -477,7 +477,7 @@ A schedule without directives. -`qiskit.pulse.transforms.remove_trivial_barriers(schedule)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/canonicalization.py "view source code") +`qiskit.pulse.transforms.remove_trivial_barriers(schedule)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/canonicalization.py "view source code") Remove trivial barriers with 0 or 1 channels. @@ -503,7 +503,7 @@ The DAG transforms create DAG representation of input program. This can be used -`qiskit.pulse.transforms.block_to_dag(block)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/dag.py "view source code") +`qiskit.pulse.transforms.block_to_dag(block)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/dag.py "view source code") Convert schedule block instruction into DAG. @@ -563,7 +563,7 @@ A sequence of transformations to generate a target code. -`qiskit.pulse.transforms.target_qobj_transform(sched, remove_directives=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/base_transforms.py "view source code") +`qiskit.pulse.transforms.target_qobj_transform(sched, remove_directives=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/base_transforms.py "view source code") A basic pulse program transformation for OpenPulse API execution. @@ -782,7 +782,7 @@ The above is just a small taste of what is possible with the builder. See the re -`qiskit.pulse.builder.build(backend=None, schedule=None, name=None, default_alignment='left')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.build(backend=None, schedule=None, name=None, default_alignment='left')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Create a context manager for launching the imperative pulse builder DSL. @@ -844,7 +844,7 @@ DriveChannel(0) -`qiskit.pulse.builder.acquire_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.acquire_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Return `AcquireChannel` for `qubit` on the active builder backend. @@ -872,7 +872,7 @@ with pulse.build(backend): -`qiskit.pulse.builder.control_channels(*qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.control_channels(*qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Return `ControlChannel` for `qubit` on the active builder backend. @@ -895,7 +895,7 @@ with pulse.build(backend): **Parameters** -**qubits** (*Iterable\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of ordered qubits of the form (control\_qubit, target\_qubit). +**qubits** ([*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of ordered qubits of the form (control\_qubit, target\_qubit). **Returns** @@ -903,13 +903,13 @@ List of control channels associated with the supplied ordered list of qubits. **Return type** -[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[chans.ControlChannel] +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.pulse.channels.ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] ### drive\_channel -`qiskit.pulse.builder.drive_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.drive_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Return `DriveChannel` for `qubit` on the active builder backend. @@ -937,7 +937,7 @@ with pulse.build(backend): -`qiskit.pulse.builder.measure_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.measure_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Return `MeasureChannel` for `qubit` on the active builder backend. @@ -998,7 +998,7 @@ drive_sched.draw() -`qiskit.pulse.builder.acquire(duration, qubit_or_channel, register, **metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.acquire(duration, qubit_or_channel, register, **metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Acquire for a `duration` on a `channel` and store the result in a `register`. @@ -1037,7 +1037,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.barrier(*channels_or_qubits, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.barrier(*channels_or_qubits, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Barrier directive for a set of channels and qubits. @@ -1106,7 +1106,7 @@ with pulse.build(backend) as pulse_prog: -`qiskit.pulse.builder.call(target, name=None, value_dict=None, **kw_params)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.call(target, name=None, value_dict=None, **kw_params)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Call the subroutine within the currently active builder context with arbitrary parameters which will be assigned to the target program. @@ -1277,7 +1277,7 @@ Currently, the backend calibrated gates are provided in the form of [`Schedule`] -`qiskit.pulse.builder.delay(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.delay(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Delay on a `channel` for a `duration`. @@ -1302,7 +1302,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.play(pulse, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.play(pulse, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Play a `pulse` on a `channel`. @@ -1327,7 +1327,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.reference(name, *extra_keys)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.reference(name, *extra_keys)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Refer to undefined subroutine by string keys. @@ -1354,7 +1354,7 @@ main_prog.assign_references(subroutine_dict={("x_gate", "q0"): subroutine}) -`qiskit.pulse.builder.set_frequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.set_frequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Set the `frequency` of a pulse `channel`. @@ -1379,7 +1379,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.set_phase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.set_phase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Set the `phase` of a pulse `channel`. @@ -1406,7 +1406,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.shift_frequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.shift_frequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Shift the `frequency` of a pulse `channel`. @@ -1431,7 +1431,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.shift_phase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.shift_phase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Shift the `phase` of a pulse `channel`. @@ -1458,7 +1458,7 @@ with pulse.build() as pulse_prog: -`qiskit.pulse.builder.snapshot(label, snapshot_type='statevector')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.snapshot(label, snapshot_type='statevector')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Simulator snapshot. @@ -1502,7 +1502,7 @@ pulse_prog.draw() -`qiskit.pulse.builder.align_equispaced(duration)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.align_equispaced(duration)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Equispaced alignment pulse scheduling context. @@ -1540,7 +1540,7 @@ None **Return type** -Generator\[(None, None, None)] +Generator\[None, None, None] **Notes** @@ -1550,7 +1550,7 @@ The scheduling is performed for sub-schedules within the context rather than cha -`qiskit.pulse.builder.align_func(duration, func)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.align_func(duration, func)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Callback defined alignment pulse scheduling context. @@ -1594,7 +1594,7 @@ None **Return type** -Generator\[(None, None, None)] +Generator\[None, None, None] **Notes** @@ -1604,7 +1604,7 @@ The scheduling is performed for sub-schedules within the context rather than cha -`qiskit.pulse.builder.align_left()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.align_left()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Left alignment pulse scheduling context. @@ -1635,13 +1635,13 @@ None **Return type** -Generator\[(None, None, None)] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[None, None, None] ### align\_right -`qiskit.pulse.builder.align_right()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.align_right()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Right alignment pulse scheduling context. @@ -1672,13 +1672,13 @@ None **Return type** -Generator\[(None, None, None)] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[None, None, None] ### align\_sequential -`qiskit.pulse.builder.align_sequential()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.align_sequential()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Sequential alignment pulse scheduling context. @@ -1709,13 +1709,13 @@ None **Return type** -Generator\[(None, None, None)] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[None, None, None] ### frequency\_offset -`qiskit.pulse.builder.frequency_offset(frequency, *channels, compensate_phase=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.frequency_offset(frequency, *channels, compensate_phase=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Shift the frequency of inputs channels on entry into context and undo on exit. @@ -1746,7 +1746,7 @@ assert len(pulse_prog.instructions) == 4 **Parameters** * **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Amount of frequency offset in Hz. -* **channels** (*chans.PulseChannel*) – Channels to offset frequency of. +* **channels** (*PulseChannel*) – Channels to offset frequency of. * **compensate\_phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Compensate for accumulated phase accumulated with respect to the channels’ frame at its initial frequency. **Yields** @@ -1755,13 +1755,13 @@ None **Return type** -Generator\[(None, None, None)] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[None, None, None] ### phase\_offset -`qiskit.pulse.builder.phase_offset(phase, *channels)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.phase_offset(phase, *channels)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Shift the phase of input channels on entry into context and undo on exit. @@ -1784,7 +1784,7 @@ assert len(pulse_prog.instructions) == 3 **Parameters** * **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Amount of phase offset in radians. -* **channels** (*chans.PulseChannel*) – Channels to offset phase of. +* **channels** (*PulseChannel*) – Channels to offset phase of. **Yields** @@ -1792,7 +1792,7 @@ None **Return type** -Generator\[(None, None, None)] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[None, None, None] ### Macros @@ -1817,7 +1817,7 @@ MemorySlot(0) -`qiskit.pulse.builder.measure(qubits, registers=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.measure(qubits, registers=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Measure a qubit within the currently active builder context. @@ -1874,7 +1874,7 @@ The `register` the qubit measurement result will be stored in. -`qiskit.pulse.builder.measure_all()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.measure_all()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Measure all qubits within the currently active builder context. @@ -1903,13 +1903,13 @@ The `register`s the qubit measurement results will be stored in. **Return type** -[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[chans.MemorySlot] +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.pulse.channels.MemorySlot](qiskit.pulse.channels.MemorySlot "qiskit.pulse.channels.MemorySlot")] ### delay\_qubits -`qiskit.pulse.builder.delay_qubits(duration, *qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.delay_qubits(duration, *qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Insert delays on all the `channels.Channel`s that correspond to the input `qubits` at the same time. @@ -1968,7 +1968,7 @@ There are 1e-06 seconds in 4500 samples. -`qiskit.pulse.builder.active_backend()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.active_backend()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Get the backend of the currently active builder context. @@ -1990,7 +1990,7 @@ builder context. -`qiskit.pulse.builder.num_qubits()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.num_qubits()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Return number of qubits in the currently active backend. @@ -2022,7 +2022,7 @@ with pulse.build(backend): -`qiskit.pulse.builder.qubit_channels(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.qubit_channels(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Returns the set of channels associated with a qubit. @@ -2052,13 +2052,13 @@ with pulse.build(backend): **Return type** -[set](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.12)")\[chans.Channel] +[set](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.12)")\[[qiskit.pulse.channels.Channel](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")] ### samples\_to\_seconds -`qiskit.pulse.builder.samples_to_seconds(samples)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.samples_to_seconds(samples)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Obtain the time in seconds that will elapse for the input number of samples on the active backend. @@ -2078,7 +2078,7 @@ The time that elapses in `samples`. -`qiskit.pulse.builder.seconds_to_samples(seconds)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/builder.py "view source code") +`qiskit.pulse.builder.seconds_to_samples(seconds)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/builder.py "view source code") Obtain the number of samples that will elapse in `seconds` on the active backend. @@ -2108,7 +2108,7 @@ The number of samples for the time to elapse -`qiskit.pulse.PulseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/exceptions.py "view source code") +`qiskit.pulse.PulseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/exceptions.py "view source code") Errors raised by the pulse module. @@ -2118,7 +2118,7 @@ Set the error message. -`qiskit.pulse.BackendNotSet(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/exceptions.py "view source code") +`qiskit.pulse.BackendNotSet(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/exceptions.py "view source code") Raised if the builder context does not have a backend. @@ -2128,7 +2128,7 @@ Set the error message. -`qiskit.pulse.NoActiveBuilder(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/exceptions.py "view source code") +`qiskit.pulse.NoActiveBuilder(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/exceptions.py "view source code") Raised if no builder context is active. @@ -2138,7 +2138,7 @@ Set the error message. -`qiskit.pulse.UnassignedDurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/exceptions.py "view source code") +`qiskit.pulse.UnassignedDurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/exceptions.py "view source code") Raised if instruction duration is unassigned. @@ -2148,7 +2148,7 @@ Set the error message. -`qiskit.pulse.UnassignedReferenceError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/exceptions.py "view source code") +`qiskit.pulse.UnassignedReferenceError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/exceptions.py "view source code") Raised if subroutine is unassigned. diff --git a/docs/api/qiskit/dev/qasm2.md b/docs/api/qiskit/dev/qasm2.md index 253b4bc8bbb..80d75b445cb 100644 --- a/docs/api/qiskit/dev/qasm2.md +++ b/docs/api/qiskit/dev/qasm2.md @@ -34,7 +34,7 @@ This module contains two public functions, both of which create a [`QuantumCircu -`qiskit.qasm2.load(filename, *, include_path=('.',), include_input_directory='append', custom_instructions=(), custom_classical=(), strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/__init__.py "view source code") +`qiskit.qasm2.load(filename, *, include_path=('.',), include_input_directory='append', custom_instructions=(), custom_classical=(), strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/__init__.py "view source code") Parse an OpenQASM 2 program from a file into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). The given path should be ASCII or UTF-8 encoded, and contain the OpenQASM 2 program. @@ -59,7 +59,7 @@ A circuit object representing the same OpenQASM 2 program. -`qiskit.qasm2.loads(string, *, include_path=('.',), custom_instructions=(), custom_classical=(), strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/__init__.py "view source code") +`qiskit.qasm2.loads(string, *, include_path=('.',), custom_instructions=(), custom_classical=(), strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/__init__.py "view source code") Parse an OpenQASM 2 program from a string into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). @@ -89,7 +89,7 @@ You can extend the quantum components of the OpenQASM 2 language by passing an i -`qiskit.qasm2.CustomInstruction(name, num_params, num_qubits, constructor, builtin=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/parse.py "view source code") +`qiskit.qasm2.CustomInstruction(name, num_params, num_qubits, constructor, builtin=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/parse.py "view source code") Information about a custom instruction that should be defined during the parse. @@ -129,7 +129,7 @@ Similar to other serialisation modules in Python, this module offers two public -`qiskit.qasm2.dump(circuit, filename_or_stream, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/export.py "view source code") +`qiskit.qasm2.dump(circuit, filename_or_stream, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/export.py "view source code") Dump a circuit as an OpenQASM 2 program to a file or stream. @@ -146,7 +146,7 @@ Dump a circuit as an OpenQASM 2 program to a file or stream. -`qiskit.qasm2.dumps(circuit, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/export.py "view source code") +`qiskit.qasm2.dumps(circuit, /)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/export.py "view source code") Export a circuit to an OpenQASM 2 program in a string. @@ -174,7 +174,7 @@ This module defines a generic error type that derives from [`QiskitError`](excep -`qiskit.qasm2.QASM2Error(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/exceptions.py "view source code") +`qiskit.qasm2.QASM2Error(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/exceptions.py "view source code") A general error raised by the OpenQASM 2 interoperation layer. @@ -186,7 +186,7 @@ In cases where the lexer or parser fails due to an invalid OpenQASM 2 file, the -`qiskit.qasm2.QASM2ParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/exceptions.py "view source code") +`qiskit.qasm2.QASM2ParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/exceptions.py "view source code") An error raised because of a failure to parse an OpenQASM 2 file. @@ -198,7 +198,7 @@ When the exporters fail to export a circuit, likely because it has structure tha -`qiskit.qasm2.QASM2ExportError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm2/exceptions.py "view source code") +`qiskit.qasm2.QASM2ExportError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm2/exceptions.py "view source code") An error raised because of a failure to convert a Qiskit object to an OpenQASM 2 form. diff --git a/docs/api/qiskit/dev/qasm3.md b/docs/api/qiskit/dev/qasm3.md index 6dc72b4543f..0c85e373aa5 100644 --- a/docs/api/qiskit/dev/qasm3.md +++ b/docs/api/qiskit/dev/qasm3.md @@ -28,7 +28,7 @@ The high-level functions are simply [`dump()`](#qiskit.qasm3.dump "qiskit.qasm3. -`qiskit.qasm3.dump(circuit, stream, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/__init__.py "view source code") +`qiskit.qasm3.dump(circuit, stream, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/__init__.py "view source code") Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object as an OpenQASM 3 stream to file-like object. @@ -42,7 +42,7 @@ Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.Qua -`qiskit.qasm3.dumps(circuit, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/__init__.py "view source code") +`qiskit.qasm3.dumps(circuit, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/__init__.py "view source code") Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object in an OpenQASM 3 string. @@ -63,7 +63,7 @@ Both of these exporter functions are single-use wrappers around the main [`Expor -`qiskit.qasm3.Exporter(includes=('stdgates.inc', ), basis_gates=('U', ), disable_constants=False, alias_classical_registers=None, allow_aliasing=None, indent='  ', experimental=ExperimentalFeatures.None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/exporter.py "view source code") +`qiskit.qasm3.Exporter(includes=('stdgates.inc', ), basis_gates=('U', ), disable_constants=False, alias_classical_registers=None, allow_aliasing=None, indent='  ', experimental=ExperimentalFeatures.None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/exporter.py "view source code") QASM3 exporter main class. @@ -117,7 +117,7 @@ All of these interfaces will raise [`QASM3ExporterError`](#qiskit.qasm3.QASM3Exp -`qiskit.qasm3.QASM3ExporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/exceptions.py "view source code") +`qiskit.qasm3.QASM3ExporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/exceptions.py "view source code") An error raised during running the OpenQASM 3 exporter. @@ -129,7 +129,7 @@ The OpenQASM 3 language is still evolving as hardware capabilities improve, so t -`qiskit.qasm3.ExperimentalFeatures(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/experimental.py "view source code") +`qiskit.qasm3.ExperimentalFeatures(value)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/experimental.py "view source code") Flags for experimental features that the OpenQASM 3 exporter supports. @@ -227,7 +227,7 @@ Currently only two high-level functions are offered, as Qiskit support for impor -`qiskit.qasm3.load(filename)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/__init__.py "view source code") +`qiskit.qasm3.load(filename)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/__init__.py "view source code") Load an OpenQASM 3 program from the file `filename`. @@ -251,7 +251,7 @@ a circuit representation of the OpenQASM 3 program. -`qiskit.qasm3.loads(program)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/__init__.py "view source code") +`qiskit.qasm3.loads(program)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/__init__.py "view source code") Load an OpenQASM 3 program from the given string. @@ -277,7 +277,7 @@ Both of these two functions raise [`QASM3ImporterError`](#qiskit.qasm3.QASM3Impo -`qiskit.qasm3.QASM3ImporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qasm3/exceptions.py "view source code") +`qiskit.qasm3.QASM3ImporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qasm3/exceptions.py "view source code") An error raised during the OpenQASM 3 importer. diff --git a/docs/api/qiskit/dev/qiskit.assembler.RunConfig.md b/docs/api/qiskit/dev/qiskit.assembler.RunConfig.md index 4d61183c719..060d977487d 100644 --- a/docs/api/qiskit/dev/qiskit.assembler.RunConfig.md +++ b/docs/api/qiskit/dev/qiskit.assembler.RunConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.assembler.RunConfig -`qiskit.assembler.RunConfig(shots=None, seed_simulator=None, memory=None, parameter_binds=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/assembler/run_config.py "view source code") +`qiskit.assembler.RunConfig(shots=None, seed_simulator=None, memory=None, parameter_binds=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/assembler/run_config.py "view source code") Bases: [`SimpleNamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.AncillaQubit.md b/docs/api/qiskit/dev/qiskit.circuit.AncillaQubit.md index a670243043f..d42568f1382 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.AncillaQubit.md +++ b/docs/api/qiskit/dev/qiskit.circuit.AncillaQubit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.AncillaQubit -`qiskit.circuit.AncillaQubit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/quantumregister.py "view source code") +`qiskit.circuit.AncillaQubit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/quantumregister.py "view source code") Bases: [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.AncillaRegister.md b/docs/api/qiskit/dev/qiskit.circuit.AncillaRegister.md index 76fbd880f62..19973db7fa2 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.AncillaRegister.md +++ b/docs/api/qiskit/dev/qiskit.circuit.AncillaRegister.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.AncillaRegister -`qiskit.circuit.AncillaRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/quantumregister.py "view source code") +`qiskit.circuit.AncillaRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/quantumregister.py "view source code") Bases: [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") diff --git a/docs/api/qiskit/dev/qiskit.circuit.Bit.md b/docs/api/qiskit/dev/qiskit.circuit.Bit.md index 89b8f8a56d9..10f6581e1b2 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Bit.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Bit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Bit -`qiskit.circuit.Bit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/bit.py "view source code") +`qiskit.circuit.Bit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/bit.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.BreakLoopOp.md b/docs/api/qiskit/dev/qiskit.circuit.BreakLoopOp.md index 1ca3dcf6a32..16348e7561a 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.BreakLoopOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.BreakLoopOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.BreakLoopOp -`qiskit.circuit.BreakLoopOp(num_qubits, num_clbits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/break_loop.py "view source code") +`qiskit.circuit.BreakLoopOp(num_qubits, num_clbits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/break_loop.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.ClassicalRegister.md b/docs/api/qiskit/dev/qiskit.circuit.ClassicalRegister.md index ca2dd90857d..afe000486e1 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ClassicalRegister.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ClassicalRegister.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ClassicalRegister -`qiskit.circuit.ClassicalRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classicalregister.py "view source code") +`qiskit.circuit.ClassicalRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classicalregister.py "view source code") Bases: [`Register`](qiskit.circuit.Register "qiskit.circuit.register.Register") @@ -40,7 +40,7 @@ Either the `size` or the `bits` argument must be provided. If `size` is not None ### instances\_counter -`= count(2)` +`= count(0)` diff --git a/docs/api/qiskit/dev/qiskit.circuit.Clbit.md b/docs/api/qiskit/dev/qiskit.circuit.Clbit.md index cb4e06042bb..a261385ec57 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Clbit.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Clbit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Clbit -`qiskit.circuit.Clbit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classicalregister.py "view source code") +`qiskit.circuit.Clbit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classicalregister.py "view source code") Bases: [`Bit`](qiskit.circuit.Bit "qiskit.circuit.bit.Bit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.ContinueLoopOp.md b/docs/api/qiskit/dev/qiskit.circuit.ContinueLoopOp.md index 42bf915db71..39cf42a81df 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ContinueLoopOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ContinueLoopOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ContinueLoopOp -`qiskit.circuit.ContinueLoopOp(num_qubits, num_clbits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/continue_loop.py "view source code") +`qiskit.circuit.ContinueLoopOp(num_qubits, num_clbits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/continue_loop.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.ControlFlowOp.md b/docs/api/qiskit/dev/qiskit.circuit.ControlFlowOp.md index 1c447824d80..8d44fd5c431 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ControlFlowOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ControlFlowOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ControlFlowOp -`qiskit.circuit.ControlFlowOp(name, num_qubits, num_clbits, params, duration=None, unit='dt', label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/control_flow.py "view source code") +`qiskit.circuit.ControlFlowOp(name, num_qubits, num_clbits, params, duration=None, unit='dt', label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/control_flow.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.ControlledGate.md b/docs/api/qiskit/dev/qiskit.circuit.ControlledGate.md index 993eb0fd2f1..1b13701fea9 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ControlledGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ControlledGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ControlledGate -`qiskit.circuit.ControlledGate(name, num_qubits, params, label=None, num_ctrl_qubits=1, definition=None, ctrl_state=None, base_gate=None, duration=None, unit=None, *, _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlledgate.py "view source code") +`qiskit.circuit.ControlledGate(name, num_qubits, params, label=None, num_ctrl_qubits=1, definition=None, ctrl_state=None, base_gate=None, duration=None, unit=None, *, _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlledgate.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") @@ -273,7 +273,7 @@ A tuple with single arguments. **Return type** -Iterable\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] ### c\_if diff --git a/docs/api/qiskit/dev/qiskit.circuit.Delay.md b/docs/api/qiskit/dev/qiskit.circuit.Delay.md index a15845188cd..9dac1fb5cd1 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Delay.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Delay.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Delay -`qiskit.circuit.Delay(duration, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/delay.py "view source code") +`qiskit.circuit.Delay(duration, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/delay.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") @@ -186,7 +186,7 @@ A tuple with single arguments. **Return type** -Iterable\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] ### c\_if diff --git a/docs/api/qiskit/dev/qiskit.circuit.EquivalenceLibrary.md b/docs/api/qiskit/dev/qiskit.circuit.EquivalenceLibrary.md index 7ab81e5942c..92d0206b509 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.EquivalenceLibrary.md +++ b/docs/api/qiskit/dev/qiskit.circuit.EquivalenceLibrary.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.EquivalenceLibrary -`qiskit.circuit.EquivalenceLibrary(*, base=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/equivalence.py "view source code") +`qiskit.circuit.EquivalenceLibrary(*, base=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/equivalence.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.ForLoopOp.md b/docs/api/qiskit/dev/qiskit.circuit.ForLoopOp.md index b0c2f067800..edeafeeface 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ForLoopOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ForLoopOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ForLoopOp -`qiskit.circuit.ForLoopOp(indexset, loop_parameter, body, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/for_loop.py "view source code") +`qiskit.circuit.ForLoopOp(indexset, loop_parameter, body, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/for_loop.py "view source code") Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") diff --git a/docs/api/qiskit/dev/qiskit.circuit.Gate.md b/docs/api/qiskit/dev/qiskit.circuit.Gate.md index eb84ba210d9..2ab3e862a7a 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Gate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Gate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Gate -`qiskit.circuit.Gate(name, num_qubits, params, label=None, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/gate.py "view source code") +`qiskit.circuit.Gate(name, num_qubits, params, label=None, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/gate.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") @@ -193,7 +193,7 @@ A tuple with single arguments. **Return type** -Iterable\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] ### c\_if diff --git a/docs/api/qiskit/dev/qiskit.circuit.IfElseOp.md b/docs/api/qiskit/dev/qiskit.circuit.IfElseOp.md index fff53be78bd..49c3a48cf2f 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.IfElseOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.IfElseOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.IfElseOp -`qiskit.circuit.IfElseOp(condition, true_body, false_body=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/if_else.py "view source code") +`qiskit.circuit.IfElseOp(condition, true_body, false_body=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/if_else.py "view source code") Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") diff --git a/docs/api/qiskit/dev/qiskit.circuit.Instruction.md b/docs/api/qiskit/dev/qiskit.circuit.Instruction.md index 60dc9135257..60ab200fd6e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Instruction.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Instruction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Instruction -`qiskit.circuit.Instruction(name, num_qubits, num_clbits, params, duration=None, unit='dt', label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/instruction.py "view source code") +`qiskit.circuit.Instruction(name, num_qubits, num_clbits, params, duration=None, unit='dt', label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/instruction.py "view source code") Bases: [`Operation`](qiskit.circuit.Operation "qiskit.circuit.operation.Operation") diff --git a/docs/api/qiskit/dev/qiskit.circuit.InstructionSet.md b/docs/api/qiskit/dev/qiskit.circuit.InstructionSet.md index e468e0861d6..3b77031c1a6 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.InstructionSet.md +++ b/docs/api/qiskit/dev/qiskit.circuit.InstructionSet.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.InstructionSet -`qiskit.circuit.InstructionSet(*, resource_requester=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/instructionset.py "view source code") +`qiskit.circuit.InstructionSet(*, resource_requester=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/instructionset.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.Operation.md b/docs/api/qiskit/dev/qiskit.circuit.Operation.md index 0d0dc00598c..2ae9bbdd9eb 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Operation.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Operation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Operation -`qiskit.circuit.Operation`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/operation.py "view source code") +`qiskit.circuit.Operation`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/operation.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.Parameter.md b/docs/api/qiskit/dev/qiskit.circuit.Parameter.md index 143134a8881..a975d294747 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Parameter.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Parameter.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Parameter -`qiskit.circuit.Parameter(name, *, uuid=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/parameter.py "view source code") +`qiskit.circuit.Parameter(name, *, uuid=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/parameter.py "view source code") Bases: [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") @@ -152,7 +152,7 @@ A new expression parameterized by any parameters which were not bound by paramet **Return type** -[ParameterExpression](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") ### conjugate @@ -164,7 +164,7 @@ Return the conjugate. **Return type** -[ParameterExpression](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") ### cos @@ -200,7 +200,7 @@ ParameterExpression representing the gradient of param\_expr w\.r.t. param or co **Return type** -[ParameterExpression](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") ### is\_real diff --git a/docs/api/qiskit/dev/qiskit.circuit.ParameterExpression.md b/docs/api/qiskit/dev/qiskit.circuit.ParameterExpression.md index b6e4638159c..3778c44a233 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ParameterExpression.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ParameterExpression.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ParameterExpression -`qiskit.circuit.ParameterExpression(symbol_map, expr)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/parameterexpression.py "view source code") +`qiskit.circuit.ParameterExpression(symbol_map, expr)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/parameterexpression.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") @@ -86,7 +86,7 @@ A new expression parameterized by any parameters which were not bound by assignm **Return type** -[ParameterExpression](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") ### bind @@ -117,7 +117,7 @@ A new expression parameterized by any parameters which were not bound by paramet **Return type** -[ParameterExpression](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") ### conjugate @@ -129,7 +129,7 @@ Return the conjugate. **Return type** -[ParameterExpression](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") ### cos @@ -165,7 +165,7 @@ ParameterExpression representing the gradient of param\_expr w\.r.t. param or co **Return type** -[ParameterExpression](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") ### is\_real @@ -248,7 +248,7 @@ A new expression with the specified parameters replaced. **Return type** -[ParameterExpression](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") ### sympify diff --git a/docs/api/qiskit/dev/qiskit.circuit.ParameterVector.md b/docs/api/qiskit/dev/qiskit.circuit.ParameterVector.md index 99f3a724a0b..9e250ab3751 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.ParameterVector.md +++ b/docs/api/qiskit/dev/qiskit.circuit.ParameterVector.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.ParameterVector -`qiskit.circuit.ParameterVector(name, length=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/parametervector.py "view source code") +`qiskit.circuit.ParameterVector(name, length=0)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/parametervector.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.md b/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.md index 721f5b91961..5a6e4880254 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.md +++ b/docs/api/qiskit/dev/qiskit.circuit.QuantumCircuit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.QuantumCircuit -`qiskit.circuit.QuantumCircuit(*regs, name=None, global_phase=0, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/quantumcircuit.py "view source code") +`qiskit.circuit.QuantumCircuit(*regs, name=None, global_phase=0, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/quantumcircuit.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") @@ -147,7 +147,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 164` +`= 182` @@ -3194,7 +3194,7 @@ q_0: ┤ bottom ├ ⊗ q_0: ┤ top ├ = q_0: ─┤ top ├── **Return type** -[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") | None +[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") | None **Examples** diff --git a/docs/api/qiskit/dev/qiskit.circuit.QuantumRegister.md b/docs/api/qiskit/dev/qiskit.circuit.QuantumRegister.md index e89e0dc9d12..d1cd3b3d2d4 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.QuantumRegister.md +++ b/docs/api/qiskit/dev/qiskit.circuit.QuantumRegister.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.QuantumRegister -`qiskit.circuit.QuantumRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/quantumregister.py "view source code") +`qiskit.circuit.QuantumRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/quantumregister.py "view source code") Bases: [`Register`](qiskit.circuit.Register "qiskit.circuit.register.Register") @@ -40,7 +40,7 @@ Either the `size` or the `bits` argument must be provided. If `size` is not None ### instances\_counter -`= count(1)` +`= count(5)` diff --git a/docs/api/qiskit/dev/qiskit.circuit.Qubit.md b/docs/api/qiskit/dev/qiskit.circuit.Qubit.md index 678c3edbe78..cd7c23fdf0e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Qubit.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Qubit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Qubit -`qiskit.circuit.Qubit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/quantumregister.py "view source code") +`qiskit.circuit.Qubit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/quantumregister.py "view source code") Bases: [`Bit`](qiskit.circuit.Bit "qiskit.circuit.bit.Bit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.Register.md b/docs/api/qiskit/dev/qiskit.circuit.Register.md index c09b13f38d3..4537124accb 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.Register.md +++ b/docs/api/qiskit/dev/qiskit.circuit.Register.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.Register -`qiskit.circuit.Register(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/register.py "view source code") +`qiskit.circuit.Register(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/register.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.SwitchCaseOp.md b/docs/api/qiskit/dev/qiskit.circuit.SwitchCaseOp.md index a3b25d35f06..5b0dda8af2d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.SwitchCaseOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.SwitchCaseOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.SwitchCaseOp -`qiskit.circuit.SwitchCaseOp(target, cases, *, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/switch_case.py "view source code") +`qiskit.circuit.SwitchCaseOp(target, cases, *, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/switch_case.py "view source code") Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") diff --git a/docs/api/qiskit/dev/qiskit.circuit.WhileLoopOp.md b/docs/api/qiskit/dev/qiskit.circuit.WhileLoopOp.md index e9fa61fc546..03cddab2456 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.WhileLoopOp.md +++ b/docs/api/qiskit/dev/qiskit.circuit.WhileLoopOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.WhileLoopOp -`qiskit.circuit.WhileLoopOp(condition, body, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/controlflow/while_loop.py "view source code") +`qiskit.circuit.WhileLoopOp(condition, body, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/controlflow/while_loop.py "view source code") Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") diff --git a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.BooleanExpression.md b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.BooleanExpression.md index 0cfb4f4ba47..3dc23660475 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.BooleanExpression.md +++ b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.BooleanExpression.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.classicalfunction.BooleanExpression -`qiskit.circuit.classicalfunction.BooleanExpression(expression, name=None, var_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classicalfunction/boolean_expression.py "view source code") +`qiskit.circuit.classicalfunction.BooleanExpression(expression, name=None, var_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classicalfunction/boolean_expression.py "view source code") Bases: `ClassicalElement` @@ -190,7 +190,7 @@ A tuple with single arguments. **Return type** -Iterable\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] ### c\_if diff --git a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunction.md b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunction.md index 50d8225a0a6..0841f68c4a2 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunction.md +++ b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.classicalfunction.ClassicalFunction -`qiskit.circuit.classicalfunction.ClassicalFunction(source, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classicalfunction/classicalfunction.py "view source code") +`qiskit.circuit.classicalfunction.ClassicalFunction(source, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classicalfunction/classicalfunction.py "view source code") Bases: `ClassicalElement` @@ -241,7 +241,7 @@ A tuple with single arguments. **Return type** -Iterable\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] ### c\_if diff --git a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md index 9facb533df0..8035f0a6774 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md +++ b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md @@ -12,7 +12,7 @@ python_api_name: qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeE -`qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classicalfunction/exceptions.py "view source code") +`qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classicalfunction/exceptions.py "view source code") ClassicalFunction compiler type error. The classicalfunction function fails at type checking time. diff --git a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md index 8c917a0605a..e1b593c45fb 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md +++ b/docs/api/qiskit/dev/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md @@ -12,7 +12,7 @@ python_api_name: qiskit.circuit.classicalfunction.ClassicalFunctionParseError -`qiskit.circuit.classicalfunction.ClassicalFunctionParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/classicalfunction/exceptions.py "view source code") +`qiskit.circuit.classicalfunction.ClassicalFunctionParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/classicalfunction/exceptions.py "view source code") ClassicalFunction compiler parse error. The classicalfunction function fails at parsing time. diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.AND.md b/docs/api/qiskit/dev/qiskit.circuit.library.AND.md index d21238e7b1d..e79e9a24ee4 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.AND.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.AND.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.AND -`qiskit.circuit.library.AND(num_variable_qubits, flags=None, mcx_mode='noancilla')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/boolean_logic/quantum_and.py "view source code") +`qiskit.circuit.library.AND(num_variable_qubits, flags=None, mcx_mode='noancilla')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/boolean_logic/quantum_and.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -80,7 +80,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 174` +`= 192` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Barrier.md b/docs/api/qiskit/dev/qiskit.circuit.library.Barrier.md index d401d9e66e3..81066496a6b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Barrier.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Barrier.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Barrier -`qiskit.circuit.library.Barrier(num_qubits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/barrier.py "view source code") +`qiskit.circuit.library.Barrier(num_qubits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/barrier.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.C3SXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.C3SXGate.md index d9bb3c068b9..8a25873f1ea 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.C3SXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.C3SXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.C3SXGate -`qiskit.circuit.library.C3SXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.C3SXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.C3XGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.C3XGate.md index 9d354310351..6d77d873140 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.C3XGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.C3XGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.C3XGate -`qiskit.circuit.library.C3XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.C3XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.C4XGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.C4XGate.md index b06922edb36..b4e64ca083b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.C4XGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.C4XGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.C4XGate -`qiskit.circuit.library.C4XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.C4XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CCXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CCXGate.md index 010e4d86adc..a67d82e2093 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CCXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CCXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CCXGate -`qiskit.circuit.library.CCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.CCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CCZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CCZGate.md index dd77c261143..386832b4e25 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CCZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CCZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CCZGate -`qiskit.circuit.library.CCZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/z.py "view source code") +`qiskit.circuit.library.CCZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/z.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.md b/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.md index 2669f109a9c..bbae0437590 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CDKMRippleCarryAdder.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CDKMRippleCarryAdder -`qiskit.circuit.library.CDKMRippleCarryAdder(num_state_qubits, kind='full', name='CDKMRippleCarryAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/adders/cdkm_ripple_carry_adder.py "view source code") +`qiskit.circuit.library.CDKMRippleCarryAdder(num_state_qubits, kind='full', name='CDKMRippleCarryAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/adders/cdkm_ripple_carry_adder.py "view source code") Bases: `Adder` @@ -126,7 +126,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 179` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CHGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CHGate.md index 7ca416b41de..3fc3abcab5e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CHGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CHGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CHGate -`qiskit.circuit.library.CHGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/h.py "view source code") +`qiskit.circuit.library.CHGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/h.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CPhaseGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CPhaseGate.md index 5887e20884f..77c828fd235 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CPhaseGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CPhaseGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CPhaseGate -`qiskit.circuit.library.CPhaseGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/p.py "view source code") +`qiskit.circuit.library.CPhaseGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/p.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CRXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CRXGate.md index 11e20d52b40..e22c8db4756 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CRXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CRXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CRXGate -`qiskit.circuit.library.CRXGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rx.py "view source code") +`qiskit.circuit.library.CRXGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rx.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CRYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CRYGate.md index 0c108d7466f..13f33b1119b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CRYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CRYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CRYGate -`qiskit.circuit.library.CRYGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/ry.py "view source code") +`qiskit.circuit.library.CRYGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/ry.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CRZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CRZGate.md index 979d2dce859..2853201f508 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CRZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CRZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CRZGate -`qiskit.circuit.library.CRZGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rz.py "view source code") +`qiskit.circuit.library.CRZGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rz.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CSGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CSGate.md index 907042e1533..841863ba972 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CSGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CSGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CSGate -`qiskit.circuit.library.CSGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/s.py "view source code") +`qiskit.circuit.library.CSGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/s.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CSXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CSXGate.md index 0ab6f4c0829..38cf5e29764 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CSXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CSXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CSXGate -`qiskit.circuit.library.CSXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/sx.py "view source code") +`qiskit.circuit.library.CSXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/sx.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CSdgGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CSdgGate.md index 0749b913c55..c6dc520697d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CSdgGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CSdgGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CSdgGate -`qiskit.circuit.library.CSdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/s.py "view source code") +`qiskit.circuit.library.CSdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/s.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CSwapGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CSwapGate.md index b2e59d0d55b..94bd57c0cea 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CSwapGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CSwapGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CSwapGate -`qiskit.circuit.library.CSwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/swap.py "view source code") +`qiskit.circuit.library.CSwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/swap.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CU1Gate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CU1Gate.md index a9677e706ab..831bd30430b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CU1Gate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CU1Gate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CU1Gate -`qiskit.circuit.library.CU1Gate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u1.py "view source code") +`qiskit.circuit.library.CU1Gate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u1.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CU3Gate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CU3Gate.md index d87610e9b32..5cf6af40800 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CU3Gate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CU3Gate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CU3Gate -`qiskit.circuit.library.CU3Gate(theta, phi, lam, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u3.py "view source code") +`qiskit.circuit.library.CU3Gate(theta, phi, lam, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u3.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CUGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CUGate.md index e7025e5f43b..cd2fd395511 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CUGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CUGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CUGate -`qiskit.circuit.library.CUGate(theta, phi, lam, gamma, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u.py "view source code") +`qiskit.circuit.library.CUGate(theta, phi, lam, gamma, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CXGate.md index 1463cae5522..09cf897a531 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CXGate -`qiskit.circuit.library.CXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.CXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CYGate.md index af69120b594..9e6e72c5640 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CYGate -`qiskit.circuit.library.CYGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/y.py "view source code") +`qiskit.circuit.library.CYGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/y.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.CZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.CZGate.md index 2413daca912..f4c4945e620 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.CZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.CZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.CZGate -`qiskit.circuit.library.CZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/z.py "view source code") +`qiskit.circuit.library.CZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/z.py "view source code") Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.DCXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.DCXGate.md index 487afafa327..0565a31e235 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.DCXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.DCXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.DCXGate -`qiskit.circuit.library.DCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/dcx.py "view source code") +`qiskit.circuit.library.DCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/dcx.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Diagonal.md b/docs/api/qiskit/dev/qiskit.circuit.library.Diagonal.md index 022ec31cb99..12db1ab9896 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Diagonal.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Diagonal.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Diagonal -`qiskit.circuit.library.Diagonal(diag)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/diagonal.py "view source code") +`qiskit.circuit.library.Diagonal(diag)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/diagonal.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -108,7 +108,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 179` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.DiagonalGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.DiagonalGate.md index 9c662ca5e1f..f69053ec40d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.DiagonalGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.DiagonalGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.DiagonalGate -`qiskit.circuit.library.DiagonalGate(diag)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/diagonal.py "view source code") +`qiskit.circuit.library.DiagonalGate(diag)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/diagonal.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.DraperQFTAdder.md b/docs/api/qiskit/dev/qiskit.circuit.library.DraperQFTAdder.md index ae3c72705ea..8b0940d5f03 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.DraperQFTAdder.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.DraperQFTAdder.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.DraperQFTAdder -`qiskit.circuit.library.DraperQFTAdder(num_state_qubits, kind='fixed', name='DraperQFTAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/adders/draper_qft_adder.py "view source code") +`qiskit.circuit.library.DraperQFTAdder(num_state_qubits, kind='fixed', name='DraperQFTAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/adders/draper_qft_adder.py "view source code") Bases: `Adder` @@ -97,7 +97,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 179` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.ECRGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.ECRGate.md index a16c07bb1fd..241d3d635bf 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.ECRGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.ECRGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.ECRGate -`qiskit.circuit.library.ECRGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/ecr.py "view source code") +`qiskit.circuit.library.ECRGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/ecr.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.EfficientSU2.md b/docs/api/qiskit/dev/qiskit.circuit.library.EfficientSU2.md index 613609f5c2f..7f30a23a4a8 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.EfficientSU2.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.EfficientSU2.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.EfficientSU2 -`qiskit.circuit.library.EfficientSU2(num_qubits=None, su2_gates=None, entanglement='reverse_linear', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='EfficientSU2', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/efficient_su2.py "view source code") +`qiskit.circuit.library.EfficientSU2(num_qubits=None, su2_gates=None, entanglement='reverse_linear', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='EfficientSU2', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/efficient_su2.py "view source code") Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") @@ -159,7 +159,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 179` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.EvolvedOperatorAnsatz.md b/docs/api/qiskit/dev/qiskit.circuit.library.EvolvedOperatorAnsatz.md index aec1dedafbc..2ff67648e1b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.EvolvedOperatorAnsatz.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.EvolvedOperatorAnsatz.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.EvolvedOperatorAnsatz -`qiskit.circuit.library.EvolvedOperatorAnsatz(operators=None, reps=1, evolution=None, insert_barriers=False, name='EvolvedOps', parameter_prefix='t', initial_state=None, flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/evolved_operator_ansatz.py "view source code") +`qiskit.circuit.library.EvolvedOperatorAnsatz(operators=None, reps=1, evolution=None, insert_barriers=False, name='EvolvedOps', parameter_prefix='t', initial_state=None, flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/evolved_operator_ansatz.py "view source code") Bases: [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.n_local.n_local.NLocal") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.ExactReciprocal.md b/docs/api/qiskit/dev/qiskit.circuit.library.ExactReciprocal.md index b993b78932f..7ec56c49224 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.ExactReciprocal.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.ExactReciprocal.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.ExactReciprocal -`qiskit.circuit.library.ExactReciprocal(num_state_qubits, scaling, neg_vals=False, name='1/x')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/exact_reciprocal.py "view source code") +`qiskit.circuit.library.ExactReciprocal(num_state_qubits, scaling, neg_vals=False, name='1/x')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/exact_reciprocal.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.ExcitationPreserving.md b/docs/api/qiskit/dev/qiskit.circuit.library.ExcitationPreserving.md index 491cd85c122..ec03982825e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.ExcitationPreserving.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.ExcitationPreserving.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.ExcitationPreserving -`qiskit.circuit.library.ExcitationPreserving(num_qubits=None, mode='iswap', entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='ExcitationPreserving', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/excitation_preserving.py "view source code") +`qiskit.circuit.library.ExcitationPreserving(num_qubits=None, mode='iswap', entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='ExcitationPreserving', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/excitation_preserving.py "view source code") Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.FourierChecking.md b/docs/api/qiskit/dev/qiskit.circuit.library.FourierChecking.md index 6bd0d7610b8..c9cd98ad29a 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.FourierChecking.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.FourierChecking.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.FourierChecking -`qiskit.circuit.library.FourierChecking(f, g)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/fourier_checking.py "view source code") +`qiskit.circuit.library.FourierChecking(f, g)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/fourier_checking.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.FunctionalPauliRotations.md b/docs/api/qiskit/dev/qiskit.circuit.library.FunctionalPauliRotations.md index d7937fac8ea..ba58c8c3689 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.FunctionalPauliRotations.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.FunctionalPauliRotations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.FunctionalPauliRotations -`qiskit.circuit.library.FunctionalPauliRotations(num_state_qubits=None, basis='Y', name='F')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/functional_pauli_rotations.py "view source code") +`qiskit.circuit.library.FunctionalPauliRotations(num_state_qubits=None, basis='Y', name='F')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/functional_pauli_rotations.py "view source code") Bases: `BlueprintCircuit`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GMS.md b/docs/api/qiskit/dev/qiskit.circuit.library.GMS.md index 6630976a710..fe884b275d4 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GMS.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GMS.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GMS -`qiskit.circuit.library.GMS(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/gms.py "view source code") +`qiskit.circuit.library.GMS(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/gms.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GR.md b/docs/api/qiskit/dev/qiskit.circuit.library.GR.md index c45650a37d9..0dbc6a2a5f3 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GR.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GR.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GR -`qiskit.circuit.library.GR(num_qubits, theta, phi)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/gr.py "view source code") +`qiskit.circuit.library.GR(num_qubits, theta, phi)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/gr.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GRX.md b/docs/api/qiskit/dev/qiskit.circuit.library.GRX.md index 4a5fe8698ab..ed84cf7da63 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GRX.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GRX.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GRX -`qiskit.circuit.library.GRX(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/gr.py "view source code") +`qiskit.circuit.library.GRX(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/gr.py "view source code") Bases: [`GR`](qiskit.circuit.library.GR "qiskit.circuit.library.generalized_gates.gr.GR") @@ -93,7 +93,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 179` +`= 160` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GRY.md b/docs/api/qiskit/dev/qiskit.circuit.library.GRY.md index 219492bfad9..e90426a4a38 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GRY.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GRY.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GRY -`qiskit.circuit.library.GRY(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/gr.py "view source code") +`qiskit.circuit.library.GRY(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/gr.py "view source code") Bases: [`GR`](qiskit.circuit.library.GR "qiskit.circuit.library.generalized_gates.gr.GR") @@ -93,7 +93,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 179` +`= 164` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GRZ.md b/docs/api/qiskit/dev/qiskit.circuit.library.GRZ.md index a5f60ce41f0..d89afd17588 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GRZ.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GRZ.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GRZ -`qiskit.circuit.library.GRZ(num_qubits, phi)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/gr.py "view source code") +`qiskit.circuit.library.GRZ(num_qubits, phi)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/gr.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -93,7 +93,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 189` +`= 167` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GlobalPhaseGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.GlobalPhaseGate.md index 3eb4ffe1179..ec24b5ef10f 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GlobalPhaseGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GlobalPhaseGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GlobalPhaseGate -`qiskit.circuit.library.GlobalPhaseGate(phase, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/global_phase.py "view source code") +`qiskit.circuit.library.GlobalPhaseGate(phase, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/global_phase.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GraphState.md b/docs/api/qiskit/dev/qiskit.circuit.library.GraphState.md index ffaa3368c21..df06fce4ed4 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GraphState.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GraphState.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GraphState -`qiskit.circuit.library.GraphState(adjacency_matrix)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/graph_state.py "view source code") +`qiskit.circuit.library.GraphState(adjacency_matrix)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/graph_state.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -98,7 +98,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 194` +`= 172` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.GroverOperator.md b/docs/api/qiskit/dev/qiskit.circuit.library.GroverOperator.md index bd3958a6801..60443d3b9cc 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.GroverOperator.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.GroverOperator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.GroverOperator -`qiskit.circuit.library.GroverOperator(oracle, state_preparation=None, zero_reflection=None, reflection_qubits=None, insert_barriers=False, mcx_mode='noancilla', name='Q')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/grover_operator.py "view source code") +`qiskit.circuit.library.GroverOperator(oracle, state_preparation=None, zero_reflection=None, reflection_qubits=None, insert_barriers=False, mcx_mode='noancilla', name='Q')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/grover_operator.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -209,7 +209,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 196` +`= 174` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.HGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.HGate.md index b6559fd6228..a7124e1cff2 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.HGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.HGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.HGate -`qiskit.circuit.library.HGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/h.py "view source code") +`qiskit.circuit.library.HGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/h.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.HRSCumulativeMultiplier.md b/docs/api/qiskit/dev/qiskit.circuit.library.HRSCumulativeMultiplier.md index 5a57e93b44d..7d8a3f60a95 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.HRSCumulativeMultiplier.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.HRSCumulativeMultiplier.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.HRSCumulativeMultiplier -`qiskit.circuit.library.HRSCumulativeMultiplier(num_state_qubits, num_result_qubits=None, adder=None, name='HRSCumulativeMultiplier')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/multipliers/hrs_cumulative_multiplier.py "view source code") +`qiskit.circuit.library.HRSCumulativeMultiplier(num_state_qubits, num_result_qubits=None, adder=None, name='HRSCumulativeMultiplier')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/multipliers/hrs_cumulative_multiplier.py "view source code") Bases: `Multiplier` @@ -110,7 +110,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 196` +`= 174` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.HamiltonianGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.HamiltonianGate.md index fcc5f9c828c..59f14e67029 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.HamiltonianGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.HamiltonianGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.HamiltonianGate -`qiskit.circuit.library.HamiltonianGate(data, time, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/hamiltonian_gate.py "view source code") +`qiskit.circuit.library.HamiltonianGate(data, time, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/hamiltonian_gate.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.HiddenLinearFunction.md b/docs/api/qiskit/dev/qiskit.circuit.library.HiddenLinearFunction.md index 5d94cffcdb3..23d50dcb74d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.HiddenLinearFunction.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.HiddenLinearFunction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.HiddenLinearFunction -`qiskit.circuit.library.HiddenLinearFunction(adjacency_matrix)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/hidden_linear_function.py "view source code") +`qiskit.circuit.library.HiddenLinearFunction(adjacency_matrix)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/hidden_linear_function.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -100,7 +100,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 198` +`= 176` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.IGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.IGate.md index b4f72aa14e6..3b111e25cf7 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.IGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.IGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.IGate -`qiskit.circuit.library.IGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/i.py "view source code") +`qiskit.circuit.library.IGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/i.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.IQP.md b/docs/api/qiskit/dev/qiskit.circuit.library.IQP.md index 6f0fc206db8..887b45539db 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.IQP.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.IQP.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.IQP -`qiskit.circuit.library.IQP(interactions)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/iqp.py "view source code") +`qiskit.circuit.library.IQP(interactions)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/iqp.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -88,7 +88,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 203` +`= 181` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Initialize.md b/docs/api/qiskit/dev/qiskit.circuit.library.Initialize.md index 184fbed76f5..cdb435eba43 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Initialize.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Initialize.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Initialize -`qiskit.circuit.library.Initialize(params, num_qubits=None, normalize=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/data_preparation/initializer.py "view source code") +`qiskit.circuit.library.Initialize(params, num_qubits=None, normalize=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/data_preparation/initializer.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.InnerProduct.md b/docs/api/qiskit/dev/qiskit.circuit.library.InnerProduct.md index d99d0f92404..d8984499ae2 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.InnerProduct.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.InnerProduct.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.InnerProduct -`qiskit.circuit.library.InnerProduct(num_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/boolean_logic/inner_product.py "view source code") +`qiskit.circuit.library.InnerProduct(num_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/boolean_logic/inner_product.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -99,7 +99,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 216` +`= 194` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.IntegerComparator.md b/docs/api/qiskit/dev/qiskit.circuit.library.IntegerComparator.md index 3e20fb0029e..1e3e86d6c30 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.IntegerComparator.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.IntegerComparator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.IntegerComparator -`qiskit.circuit.library.IntegerComparator(num_state_qubits=None, value=None, geq=True, name='cmp')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/integer_comparator.py "view source code") +`qiskit.circuit.library.IntegerComparator(num_state_qubits=None, value=None, geq=True, name='cmp')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/integer_comparator.py "view source code") Bases: `BlueprintCircuit` @@ -79,7 +79,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 218` +`= 196` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Isometry.md b/docs/api/qiskit/dev/qiskit.circuit.library.Isometry.md index feceddc73ac..386b6100e51 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Isometry.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Isometry.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Isometry -`qiskit.circuit.library.Isometry(isometry, num_ancillas_zero, num_ancillas_dirty, epsilon=1e-10)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/isometry.py "view source code") +`qiskit.circuit.library.Isometry(isometry, num_ancillas_zero, num_ancillas_dirty, epsilon=1e-10)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/isometry.py "view source code") Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.LinearAmplitudeFunction.md b/docs/api/qiskit/dev/qiskit.circuit.library.LinearAmplitudeFunction.md index d74addd9cee..b77e5e03a7a 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.LinearAmplitudeFunction.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.LinearAmplitudeFunction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.LinearAmplitudeFunction -`qiskit.circuit.library.LinearAmplitudeFunction(num_state_qubits, slope, offset, domain, image, rescaling_factor=1, breakpoints=None, name='F')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/linear_amplitude_function.py "view source code") +`qiskit.circuit.library.LinearAmplitudeFunction(num_state_qubits, slope, offset, domain, image, rescaling_factor=1, breakpoints=None, name='F')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/linear_amplitude_function.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -114,7 +114,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 218` +`= 196` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.LinearFunction.md b/docs/api/qiskit/dev/qiskit.circuit.library.LinearFunction.md index fe0eec242f3..93adda5fa47 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.LinearFunction.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.LinearFunction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.LinearFunction -`qiskit.circuit.library.LinearFunction(linear, validate_input=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/linear_function.py "view source code") +`qiskit.circuit.library.LinearFunction(linear, validate_input=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/linear_function.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.LinearPauliRotations.md b/docs/api/qiskit/dev/qiskit.circuit.library.LinearPauliRotations.md index 49fa1902175..76e37a6432c 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.LinearPauliRotations.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.LinearPauliRotations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.LinearPauliRotations -`qiskit.circuit.library.LinearPauliRotations(num_state_qubits=None, slope=1, offset=0, basis='Y', name='LinRot')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/linear_pauli_rotations.py "view source code") +`qiskit.circuit.library.LinearPauliRotations(num_state_qubits=None, slope=1, offset=0, basis='Y', name='LinRot')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/linear_pauli_rotations.py "view source code") Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") @@ -95,7 +95,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 218` +`= 196` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCMT.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCMT.md index e3bb92eb3bb..cac16537165 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCMT.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCMT.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCMT -`qiskit.circuit.library.MCMT(gate, num_ctrl_qubits, num_target_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/mcmt.py "view source code") +`qiskit.circuit.library.MCMT(gate, num_ctrl_qubits, num_target_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/mcmt.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -92,7 +92,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 218` +`= 196` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCMTVChain.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCMTVChain.md index 905c16727ab..480d67c4a9d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCMTVChain.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCMTVChain.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCMTVChain -`qiskit.circuit.library.MCMTVChain(gate, num_ctrl_qubits, num_target_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/mcmt.py "view source code") +`qiskit.circuit.library.MCMTVChain(gate, num_ctrl_qubits, num_target_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/mcmt.py "view source code") Bases: [`MCMT`](qiskit.circuit.library.MCMT "qiskit.circuit.library.generalized_gates.mcmt.MCMT") @@ -116,7 +116,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 219` +`= 197` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCPhaseGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCPhaseGate.md index b5098153962..413e20ff453 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCPhaseGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCPhaseGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCPhaseGate -`qiskit.circuit.library.MCPhaseGate(lam, num_ctrl_qubits, label=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/p.py "view source code") +`qiskit.circuit.library.MCPhaseGate(lam, num_ctrl_qubits, label=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/p.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCXGate.md index c7b561663a5..7442c14f279 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCXGate -`qiskit.circuit.library.MCXGate(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.MCXGate(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCXGrayCode.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCXGrayCode.md index 1c03c287d5f..0ba78cbb15f 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCXGrayCode.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCXGrayCode.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCXGrayCode -`qiskit.circuit.library.MCXGrayCode(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.MCXGrayCode(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.standard_gates.x.MCXGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCXRecursive.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCXRecursive.md index 9a563d72e96..b14fafe738d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCXRecursive.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCXRecursive.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCXRecursive -`qiskit.circuit.library.MCXRecursive(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.MCXRecursive(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.standard_gates.x.MCXGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MCXVChain.md b/docs/api/qiskit/dev/qiskit.circuit.library.MCXVChain.md index 7898ef3f32e..175d410b95e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MCXVChain.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MCXVChain.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MCXVChain -`qiskit.circuit.library.MCXVChain(num_ctrl_qubits=None, dirty_ancillas=False, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.MCXVChain(num_ctrl_qubits=None, dirty_ancillas=False, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.standard_gates.x.MCXGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.MSGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.MSGate.md index e6da4fcbe0b..d5e21df11a7 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.MSGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.MSGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.MSGate -`qiskit.circuit.library.MSGate(num_qubits, theta, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/gms.py "view source code") +`qiskit.circuit.library.MSGate(num_qubits, theta, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/gms.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Measure.md b/docs/api/qiskit/dev/qiskit.circuit.library.Measure.md index 554394284a8..0cccc391e04 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Measure.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Measure.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Measure -`qiskit.circuit.library.Measure(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/measure.py "view source code") +`qiskit.circuit.library.Measure(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/measure.py "view source code") Bases: [`SingletonInstruction`](circuit_singleton#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.NLocal.md b/docs/api/qiskit/dev/qiskit.circuit.library.NLocal.md index d0eeb066b3b..00a19ae09fa 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.NLocal.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.NLocal.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.NLocal -`qiskit.circuit.library.NLocal(num_qubits=None, rotation_blocks=None, entanglement_blocks=None, entanglement=None, reps=1, insert_barriers=False, parameter_prefix='θ', overwrite_block_parameters=True, skip_final_rotation_layer=False, skip_unentangled_qubits=False, initial_state=None, name='nlocal', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/n_local.py "view source code") +`qiskit.circuit.library.NLocal(num_qubits=None, rotation_blocks=None, entanglement_blocks=None, entanglement=None, reps=1, insert_barriers=False, parameter_prefix='θ', overwrite_block_parameters=True, skip_final_rotation_layer=False, skip_unentangled_qubits=False, initial_state=None, name='nlocal', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/n_local.py "view source code") Bases: `BlueprintCircuit` @@ -145,7 +145,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 220` +`= 198` @@ -414,7 +414,7 @@ The entangler map for the current block in the current repetition. **Return type** -Sequence\[Sequence\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] +[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] ### get\_unentangled\_qubits diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.OR.md b/docs/api/qiskit/dev/qiskit.circuit.library.OR.md index af4e776468d..58c8b1c8095 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.OR.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.OR.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.OR -`qiskit.circuit.library.OR(num_variable_qubits, flags=None, mcx_mode='noancilla')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/boolean_logic/quantum_or.py "view source code") +`qiskit.circuit.library.OR(num_variable_qubits, flags=None, mcx_mode='noancilla')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/boolean_logic/quantum_or.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -80,7 +80,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 223` +`= 201` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PauliEvolutionGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.PauliEvolutionGate.md index 8d62a8886b0..571b8c1af8d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PauliEvolutionGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PauliEvolutionGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PauliEvolutionGate -`qiskit.circuit.library.PauliEvolutionGate(operator, time=1.0, label=None, synthesis=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/pauli_evolution.py "view source code") +`qiskit.circuit.library.PauliEvolutionGate(operator, time=1.0, label=None, synthesis=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/pauli_evolution.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PauliFeatureMap.md b/docs/api/qiskit/dev/qiskit.circuit.library.PauliFeatureMap.md index 0c500de802b..b115bc645dc 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PauliFeatureMap.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PauliFeatureMap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PauliFeatureMap -`qiskit.circuit.library.PauliFeatureMap(feature_dimension=None, reps=2, entanglement='full', alpha=2.0, paulis=None, data_map_func=None, parameter_prefix='x', insert_barriers=False, name='PauliFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/data_preparation/pauli_feature_map.py "view source code") +`qiskit.circuit.library.PauliFeatureMap(feature_dimension=None, reps=2, entanglement='full', alpha=2.0, paulis=None, data_map_func=None, parameter_prefix='x', insert_barriers=False, name='PauliFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/data_preparation/pauli_feature_map.py "view source code") Bases: [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.n_local.n_local.NLocal") @@ -208,7 +208,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 228` +`= 206` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PauliGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.PauliGate.md index 2114f3b42d8..e5bba4cfefd 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PauliGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PauliGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PauliGate -`qiskit.circuit.library.PauliGate(label)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/pauli.py "view source code") +`qiskit.circuit.library.PauliGate(label)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/pauli.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PauliTwoDesign.md b/docs/api/qiskit/dev/qiskit.circuit.library.PauliTwoDesign.md index 6e6043b6540..0bd0a5fb194 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PauliTwoDesign.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PauliTwoDesign.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PauliTwoDesign -`qiskit.circuit.library.PauliTwoDesign(num_qubits=None, reps=3, seed=None, insert_barriers=False, name='PauliTwoDesign')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/pauli_two_design.py "view source code") +`qiskit.circuit.library.PauliTwoDesign(num_qubits=None, reps=3, seed=None, insert_barriers=False, name='PauliTwoDesign')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/pauli_two_design.py "view source code") Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") @@ -143,7 +143,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 229` +`= 207` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Permutation.md b/docs/api/qiskit/dev/qiskit.circuit.library.Permutation.md index ff24e7cbfc2..b222b5e3101 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Permutation.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Permutation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Permutation -`qiskit.circuit.library.Permutation(num_qubits, pattern=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/permutation.py "view source code") +`qiskit.circuit.library.Permutation(num_qubits, pattern=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/permutation.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -82,7 +82,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 247` +`= 225` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PermutationGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.PermutationGate.md index fe673a68824..53789e1e21e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PermutationGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PermutationGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PermutationGate -`qiskit.circuit.library.PermutationGate(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/permutation.py "view source code") +`qiskit.circuit.library.PermutationGate(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/permutation.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PhaseEstimation.md b/docs/api/qiskit/dev/qiskit.circuit.library.PhaseEstimation.md index 9f685dc9cd6..db3c83e2e28 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PhaseEstimation.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PhaseEstimation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PhaseEstimation -`qiskit.circuit.library.PhaseEstimation(num_evaluation_qubits, unitary, iqft=None, name='QPE')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/phase_estimation.py "view source code") +`qiskit.circuit.library.PhaseEstimation(num_evaluation_qubits, unitary, iqft=None, name='QPE')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/phase_estimation.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -99,7 +99,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 301` +`= 207` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PhaseGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.PhaseGate.md index f55341ccf79..80eb8d31aa6 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PhaseGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PhaseGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PhaseGate -`qiskit.circuit.library.PhaseGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/p.py "view source code") +`qiskit.circuit.library.PhaseGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/p.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PhaseOracle.md b/docs/api/qiskit/dev/qiskit.circuit.library.PhaseOracle.md index b352ed2a991..e95b5da922e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PhaseOracle.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PhaseOracle.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PhaseOracle -`qiskit.circuit.library.PhaseOracle(expression, synthesizer=None, var_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/phase_oracle.py "view source code") +`qiskit.circuit.library.PhaseOracle(expression, synthesizer=None, var_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/phase_oracle.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -76,7 +76,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 303` +`= 209` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseChebyshev.md b/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseChebyshev.md index 7e1b687a8cd..9641b4d949e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseChebyshev.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseChebyshev.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PiecewiseChebyshev -`qiskit.circuit.library.PiecewiseChebyshev(f_x, degree=None, breakpoints=None, num_state_qubits=None, name='pw_cheb')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/piecewise_chebyshev.py "view source code") +`qiskit.circuit.library.PiecewiseChebyshev(f_x, degree=None, breakpoints=None, num_state_qubits=None, name='pw_cheb')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/piecewise_chebyshev.py "view source code") Bases: `BlueprintCircuit` @@ -121,7 +121,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 305` +`= 211` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseLinearPauliRotations.md b/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseLinearPauliRotations.md index 5a008fd4850..dd3b7a6cefc 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseLinearPauliRotations.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PiecewiseLinearPauliRotations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PiecewiseLinearPauliRotations -`qiskit.circuit.library.PiecewiseLinearPauliRotations(num_state_qubits=None, breakpoints=None, slopes=None, offsets=None, basis='Y', name='pw_lin')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/piecewise_linear_pauli_rotations.py "view source code") +`qiskit.circuit.library.PiecewiseLinearPauliRotations(num_state_qubits=None, breakpoints=None, slopes=None, offsets=None, basis='Y', name='pw_lin')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/piecewise_linear_pauli_rotations.py "view source code") Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") @@ -104,7 +104,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 365` +`= 271` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md b/docs/api/qiskit/dev/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md index c2949083fbe..4542591517d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PiecewisePolynomialPauliRotations -`qiskit.circuit.library.PiecewisePolynomialPauliRotations(num_state_qubits=None, breakpoints=None, coeffs=None, basis='Y', name='pw_poly')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/piecewise_polynomial_pauli_rotations.py "view source code") +`qiskit.circuit.library.PiecewisePolynomialPauliRotations(num_state_qubits=None, breakpoints=None, coeffs=None, basis='Y', name='pw_poly')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/piecewise_polynomial_pauli_rotations.py "view source code") Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") @@ -162,7 +162,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 305` +`= 211` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.PolynomialPauliRotations.md b/docs/api/qiskit/dev/qiskit.circuit.library.PolynomialPauliRotations.md index 008609409a4..ac2c8147526 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.PolynomialPauliRotations.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.PolynomialPauliRotations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.PolynomialPauliRotations -`qiskit.circuit.library.PolynomialPauliRotations(num_state_qubits=None, coeffs=None, basis='Y', name='poly')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/polynomial_pauli_rotations.py "view source code") +`qiskit.circuit.library.PolynomialPauliRotations(num_state_qubits=None, coeffs=None, basis='Y', name='poly')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/polynomial_pauli_rotations.py "view source code") Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") @@ -122,7 +122,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 158` +`= 214` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.QAOAAnsatz.md b/docs/api/qiskit/dev/qiskit.circuit.library.QAOAAnsatz.md index bbc3c082ce2..094756243ab 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.QAOAAnsatz.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.QAOAAnsatz.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.QAOAAnsatz -`qiskit.circuit.library.QAOAAnsatz(cost_operator=None, reps=1, initial_state=None, mixer_operator=None, name='QAOA', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/qaoa_ansatz.py "view source code") +`qiskit.circuit.library.QAOAAnsatz(cost_operator=None, reps=1, initial_state=None, mixer_operator=None, name='QAOA', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/qaoa_ansatz.py "view source code") Bases: [`EvolvedOperatorAnsatz`](qiskit.circuit.library.EvolvedOperatorAnsatz "qiskit.circuit.library.n_local.evolved_operator_ansatz.EvolvedOperatorAnsatz") @@ -137,7 +137,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 158` +`= 271` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.QFT.md b/docs/api/qiskit/dev/qiskit.circuit.library.QFT.md index d05b6bd8f1b..7a14c1f974c 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.QFT.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.QFT.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.QFT -`qiskit.circuit.library.QFT(num_qubits=None, approximation_degree=0, do_swaps=True, inverse=False, insert_barriers=False, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/basis_change/qft.py "view source code") +`qiskit.circuit.library.QFT(num_qubits=None, approximation_degree=0, do_swaps=True, inverse=False, insert_barriers=False, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/basis_change/qft.py "view source code") Bases: `BlueprintCircuit` @@ -115,7 +115,7 @@ True, if barriers are inserted, False if not. ### instances -`= 161` +`= 169` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.QuadraticForm.md b/docs/api/qiskit/dev/qiskit.circuit.library.QuadraticForm.md index ccc355ededf..a3233eca226 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.QuadraticForm.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.QuadraticForm.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.QuadraticForm -`qiskit.circuit.library.QuadraticForm(num_result_qubits=None, quadratic=None, linear=None, offset=None, little_endian=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/quadratic_form.py "view source code") +`qiskit.circuit.library.QuadraticForm(num_result_qubits=None, quadratic=None, linear=None, offset=None, little_endian=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/quadratic_form.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -101,7 +101,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 170` +`= 283` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.md b/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.md index 4a679d38a39..317de5945e8 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.QuantumVolume.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.QuantumVolume -`qiskit.circuit.library.QuantumVolume(num_qubits, depth=None, seed=None, classical_permutation=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/quantum_volume.py "view source code") +`qiskit.circuit.library.QuantumVolume(num_qubits, depth=None, seed=None, classical_permutation=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/quantum_volume.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -87,7 +87,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 173` +`= 286` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RC3XGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RC3XGate.md index 8b110ae2538..53c5f85edcc 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RC3XGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RC3XGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RC3XGate -`qiskit.circuit.library.RC3XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.RC3XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RCCXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RCCXGate.md index 9ed0e6b739d..73e94f5c584 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RCCXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RCCXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RCCXGate -`qiskit.circuit.library.RCCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.RCCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.md b/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.md index bc5ef735bef..9717e7f1142 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RGQFTMultiplier.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RGQFTMultiplier -`qiskit.circuit.library.RGQFTMultiplier(num_state_qubits, num_result_qubits=None, name='RGQFTMultiplier')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/multipliers/rg_qft_multiplier.py "view source code") +`qiskit.circuit.library.RGQFTMultiplier(num_state_qubits, num_result_qubits=None, name='RGQFTMultiplier')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/multipliers/rg_qft_multiplier.py "view source code") Bases: `Multiplier` @@ -89,7 +89,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 304` +`= 417` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RGate.md index 50cfea01953..7ffa9bd7c8f 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RGate -`qiskit.circuit.library.RGate(theta, phi, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/r.py "view source code") +`qiskit.circuit.library.RGate(theta, phi, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/r.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RVGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RVGate.md index ec7f8bd825a..e94745c4fa8 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RVGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RVGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RVGate -`qiskit.circuit.library.RVGate(v_x, v_y, v_z, basis='U')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/rv.py "view source code") +`qiskit.circuit.library.RVGate(v_x, v_y, v_z, basis='U')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/rv.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RXGate.md index 585ecde13a2..f3a907fb1e6 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RXGate -`qiskit.circuit.library.RXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rx.py "view source code") +`qiskit.circuit.library.RXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rx.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RXXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RXXGate.md index 004fb185ea8..eac13c82134 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RXXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RXXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RXXGate -`qiskit.circuit.library.RXXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rxx.py "view source code") +`qiskit.circuit.library.RXXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rxx.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RYGate.md index a9d552c2f3c..a61e5c744b6 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RYGate -`qiskit.circuit.library.RYGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/ry.py "view source code") +`qiskit.circuit.library.RYGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/ry.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RYYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RYYGate.md index 14f14e7b54a..7144a4fa470 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RYYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RYYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RYYGate -`qiskit.circuit.library.RYYGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/ryy.py "view source code") +`qiskit.circuit.library.RYYGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/ryy.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RZGate.md index 0119d9e5d2e..433bd655915 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RZGate -`qiskit.circuit.library.RZGate(phi, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rz.py "view source code") +`qiskit.circuit.library.RZGate(phi, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rz.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RZXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RZXGate.md index 64802022c54..26076437cd5 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RZXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RZXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RZXGate -`qiskit.circuit.library.RZXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rzx.py "view source code") +`qiskit.circuit.library.RZXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rzx.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RZZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.RZZGate.md index 6f3c7993b8f..363007ec57c 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RZZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RZZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RZZGate -`qiskit.circuit.library.RZZGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/rzz.py "view source code") +`qiskit.circuit.library.RZZGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/rzz.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.md b/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.md index 13bfb184b14..143907422c0 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.RealAmplitudes.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.RealAmplitudes -`qiskit.circuit.library.RealAmplitudes(num_qubits=None, entanglement='reverse_linear', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='RealAmplitudes', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/real_amplitudes.py "view source code") +`qiskit.circuit.library.RealAmplitudes(num_qubits=None, entanglement='reverse_linear', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='RealAmplitudes', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/real_amplitudes.py "view source code") Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") @@ -197,7 +197,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 304` +`= 417` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.Reset.md b/docs/api/qiskit/dev/qiskit.circuit.library.Reset.md index 98eb604241c..4ab3a31470e 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.Reset.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.Reset.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.Reset -`qiskit.circuit.library.Reset(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/reset.py "view source code") +`qiskit.circuit.library.Reset(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/reset.py "view source code") Bases: [`SingletonInstruction`](circuit_singleton#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.SGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.SGate.md index 1f23c832d19..fa97c68bf9d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.SGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.SGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.SGate -`qiskit.circuit.library.SGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/s.py "view source code") +`qiskit.circuit.library.SGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/s.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.SXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.SXGate.md index aea17039151..bfd8d7ae3fc 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.SXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.SXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.SXGate -`qiskit.circuit.library.SXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/sx.py "view source code") +`qiskit.circuit.library.SXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/sx.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.SXdgGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.SXdgGate.md index 484f05a02ab..7746508140b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.SXdgGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.SXdgGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.SXdgGate -`qiskit.circuit.library.SXdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/sx.py "view source code") +`qiskit.circuit.library.SXdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/sx.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.SdgGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.SdgGate.md index 547fa331832..671ac8f0b20 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.SdgGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.SdgGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.SdgGate -`qiskit.circuit.library.SdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/s.py "view source code") +`qiskit.circuit.library.SdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/s.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.StatePreparation.md b/docs/api/qiskit/dev/qiskit.circuit.library.StatePreparation.md index cf93ce2ed58..b860ffe3af8 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.StatePreparation.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.StatePreparation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.StatePreparation -`qiskit.circuit.library.StatePreparation(params, num_qubits=None, inverse=False, label=None, normalize=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/data_preparation/state_preparation.py "view source code") +`qiskit.circuit.library.StatePreparation(params, num_qubits=None, inverse=False, label=None, normalize=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/data_preparation/state_preparation.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.SwapGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.SwapGate.md index 6ef613050dc..d922e3f925b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.SwapGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.SwapGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.SwapGate -`qiskit.circuit.library.SwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/swap.py "view source code") +`qiskit.circuit.library.SwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/swap.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.TGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.TGate.md index 2b62d1203af..3b6b2ef4f8d 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.TGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.TGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.TGate -`qiskit.circuit.library.TGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/t.py "view source code") +`qiskit.circuit.library.TGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/t.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.TdgGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.TdgGate.md index a66b0d76dd1..0954839a216 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.TdgGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.TdgGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.TdgGate -`qiskit.circuit.library.TdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/t.py "view source code") +`qiskit.circuit.library.TdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/t.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.md b/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.md index 17a30fdcff8..32b78b90e22 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.TwoLocal.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.TwoLocal -`qiskit.circuit.library.TwoLocal(num_qubits=None, rotation_blocks=None, entanglement_blocks=None, entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='TwoLocal', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/n_local/two_local.py "view source code") +`qiskit.circuit.library.TwoLocal(num_qubits=None, rotation_blocks=None, entanglement_blocks=None, entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='TwoLocal', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/n_local/two_local.py "view source code") Bases: [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.n_local.n_local.NLocal") @@ -209,7 +209,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 304` +`= 417` @@ -399,5 +399,5 @@ Overloading to handle the special case of 1 qubit where the entanglement are ign **Return type** -Sequence\[Sequence\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] +[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.U1Gate.md b/docs/api/qiskit/dev/qiskit.circuit.library.U1Gate.md index 5aae9626ccd..7ea4550a455 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.U1Gate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.U1Gate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.U1Gate -`qiskit.circuit.library.U1Gate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u1.py "view source code") +`qiskit.circuit.library.U1Gate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u1.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.U2Gate.md b/docs/api/qiskit/dev/qiskit.circuit.library.U2Gate.md index 72376533e36..f59425e86a1 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.U2Gate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.U2Gate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.U2Gate -`qiskit.circuit.library.U2Gate(phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u2.py "view source code") +`qiskit.circuit.library.U2Gate(phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u2.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.U3Gate.md b/docs/api/qiskit/dev/qiskit.circuit.library.U3Gate.md index 979ecfb22ce..a72194fa5e4 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.U3Gate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.U3Gate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.U3Gate -`qiskit.circuit.library.U3Gate(theta, phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u3.py "view source code") +`qiskit.circuit.library.U3Gate(theta, phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u3.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UCGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UCGate.md index 296430f0551..1c6e39b1b8b 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UCGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UCGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UCGate -`qiskit.circuit.library.UCGate(gate_list, up_to_diagonal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/uc.py "view source code") +`qiskit.circuit.library.UCGate(gate_list, up_to_diagonal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/uc.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UCPauliRotGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UCPauliRotGate.md index 19c24dec039..880e153cd42 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UCPauliRotGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UCPauliRotGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UCPauliRotGate -`qiskit.circuit.library.UCPauliRotGate(angle_list, rot_axis)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/uc_pauli_rot.py "view source code") +`qiskit.circuit.library.UCPauliRotGate(angle_list, rot_axis)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/uc_pauli_rot.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UCRXGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UCRXGate.md index 18007c4cd46..5e6ae27f4f0 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UCRXGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UCRXGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UCRXGate -`qiskit.circuit.library.UCRXGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/ucrx.py "view source code") +`qiskit.circuit.library.UCRXGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/ucrx.py "view source code") Bases: [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.generalized_gates.uc_pauli_rot.UCPauliRotGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UCRYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UCRYGate.md index 70fdd7b3dbf..c38f6d98457 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UCRYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UCRYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UCRYGate -`qiskit.circuit.library.UCRYGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/ucry.py "view source code") +`qiskit.circuit.library.UCRYGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/ucry.py "view source code") Bases: [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.generalized_gates.uc_pauli_rot.UCPauliRotGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UCRZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UCRZGate.md index 61ce9e46fc8..6e9bcb48169 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UCRZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UCRZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UCRZGate -`qiskit.circuit.library.UCRZGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/ucrz.py "view source code") +`qiskit.circuit.library.UCRZGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/ucrz.py "view source code") Bases: [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.generalized_gates.uc_pauli_rot.UCPauliRotGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UGate.md index 3acf68457ae..6ed31a08cc3 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UGate -`qiskit.circuit.library.UGate(theta, phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/u.py "view source code") +`qiskit.circuit.library.UGate(theta, phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/u.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryGate.md index 9497dc9873d..e9b81cd47d6 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UnitaryGate -`qiskit.circuit.library.UnitaryGate(data, label=None, check_input=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/generalized_gates/unitary.py "view source code") +`qiskit.circuit.library.UnitaryGate(data, label=None, check_input=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/generalized_gates/unitary.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.md b/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.md index 97950ee33f4..c0429fdc2f0 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.UnitaryOverlap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.UnitaryOverlap -`qiskit.circuit.library.UnitaryOverlap(unitary1, unitary2, prefix1='p1', prefix2='p2')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/overlap.py "view source code") +`qiskit.circuit.library.UnitaryOverlap(unitary1, unitary2, prefix1='p1', prefix2='p2')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/overlap.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -109,7 +109,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 304` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.md b/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.md index 9915bacf142..74a9b4741e9 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.VBERippleCarryAdder.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.VBERippleCarryAdder -`qiskit.circuit.library.VBERippleCarryAdder(num_state_qubits, kind='full', name='VBERippleCarryAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/adders/vbe_ripple_carry_adder.py "view source code") +`qiskit.circuit.library.VBERippleCarryAdder(num_state_qubits, kind='full', name='VBERippleCarryAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/adders/vbe_ripple_carry_adder.py "view source code") Bases: `Adder` @@ -98,7 +98,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 304` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.WeightedAdder.md b/docs/api/qiskit/dev/qiskit.circuit.library.WeightedAdder.md index 9738e71aee4..5160608fb71 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.WeightedAdder.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.WeightedAdder.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.WeightedAdder -`qiskit.circuit.library.WeightedAdder(num_state_qubits=None, weights=None, name='adder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/arithmetic/weighted_adder.py "view source code") +`qiskit.circuit.library.WeightedAdder(num_state_qubits=None, weights=None, name='adder')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/arithmetic/weighted_adder.py "view source code") Bases: `BlueprintCircuit` @@ -101,7 +101,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 304` +`= 158` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.XGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.XGate.md index 681603d2c98..28591b49868 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.XGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.XGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.XGate -`qiskit.circuit.library.XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/x.py "view source code") +`qiskit.circuit.library.XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/x.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.XOR.md b/docs/api/qiskit/dev/qiskit.circuit.library.XOR.md index ea2dc4f39e4..3586d8c26ea 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.XOR.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.XOR.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.XOR -`qiskit.circuit.library.XOR(num_qubits, amount=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/boolean_logic/quantum_xor.py "view source code") +`qiskit.circuit.library.XOR(num_qubits, amount=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/boolean_logic/quantum_xor.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") @@ -82,7 +82,7 @@ Return the global phase of the current circuit scope in radians. ### instances -`= 306` +`= 160` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.XXMinusYYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.XXMinusYYGate.md index 6ae2b88aa35..33602131635 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.XXMinusYYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.XXMinusYYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.XXMinusYYGate -`qiskit.circuit.library.XXMinusYYGate(theta, beta=0, label='(XX-YY)', *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/xx_minus_yy.py "view source code") +`qiskit.circuit.library.XXMinusYYGate(theta, beta=0, label='(XX-YY)', *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/xx_minus_yy.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.XXPlusYYGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.XXPlusYYGate.md index e775c88745e..fabe5a522f7 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.XXPlusYYGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.XXPlusYYGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.XXPlusYYGate -`qiskit.circuit.library.XXPlusYYGate(theta, beta=0, label='(XX+YY)', *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/xx_plus_yy.py "view source code") +`qiskit.circuit.library.XXPlusYYGate(theta, beta=0, label='(XX+YY)', *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/xx_plus_yy.py "view source code") Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.YGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.YGate.md index 9f235042841..cb5cf9cc3d6 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.YGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.YGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.YGate -`qiskit.circuit.library.YGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/y.py "view source code") +`qiskit.circuit.library.YGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/y.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.ZFeatureMap.md b/docs/api/qiskit/dev/qiskit.circuit.library.ZFeatureMap.md index c940fb9aa48..b42b33b9d21 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.ZFeatureMap.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.ZFeatureMap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.ZFeatureMap -`qiskit.circuit.library.ZFeatureMap(feature_dimension, reps=2, data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/data_preparation/z_feature_map.py "view source code") +`qiskit.circuit.library.ZFeatureMap(feature_dimension, reps=2, data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/data_preparation/z_feature_map.py "view source code") Bases: [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.data_preparation.pauli_feature_map.PauliFeatureMap") @@ -175,7 +175,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 308` +`= 162` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.ZGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.ZGate.md index 2a7bb6a52d6..aa7f2a36f23 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.ZGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.ZGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.ZGate -`qiskit.circuit.library.ZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/z.py "view source code") +`qiskit.circuit.library.ZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/z.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.ZZFeatureMap.md b/docs/api/qiskit/dev/qiskit.circuit.library.ZZFeatureMap.md index e62c51bcba3..ab91486a6b4 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.ZZFeatureMap.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.ZZFeatureMap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.ZZFeatureMap -`qiskit.circuit.library.ZZFeatureMap(feature_dimension, reps=2, entanglement='full', data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZZFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/data_preparation/zz_feature_map.py "view source code") +`qiskit.circuit.library.ZZFeatureMap(feature_dimension, reps=2, entanglement='full', data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZZFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/data_preparation/zz_feature_map.py "view source code") Bases: [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.data_preparation.pauli_feature_map.PauliFeatureMap") @@ -180,7 +180,7 @@ If barriers are inserted in between the layers or not. ### instances -`= 308` +`= 162` diff --git a/docs/api/qiskit/dev/qiskit.circuit.library.iSwapGate.md b/docs/api/qiskit/dev/qiskit.circuit.library.iSwapGate.md index 958589def39..72c99fa92db 100644 --- a/docs/api/qiskit/dev/qiskit.circuit.library.iSwapGate.md +++ b/docs/api/qiskit/dev/qiskit.circuit.library.iSwapGate.md @@ -10,7 +10,7 @@ python_api_name: qiskit.circuit.library.iSwapGate -`qiskit.circuit.library.iSwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/circuit/library/standard_gates/iswap.py "view source code") +`qiskit.circuit.library.iSwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/circuit/library/standard_gates/iswap.py "view source code") Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGCircuit.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGCircuit.md index 6f3fcd16097..3f75d46ba49 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGCircuit.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGCircuit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGCircuit -`qiskit.dagcircuit.DAGCircuit`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagcircuit.py "view source code") +`qiskit.dagcircuit.DAGCircuit`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagcircuit.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDepNode.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDepNode.md index 426f406b330..fd873a38928 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDepNode.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDepNode.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGDepNode -`qiskit.dagcircuit.DAGDepNode(type=None, op=None, name=None, qargs=(), cargs=(), successors=None, predecessors=None, reachable=None, matchedwith=None, successorstovisit=None, isblocked=None, qindices=None, cindices=None, nid=-1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagdepnode.py "view source code") +`qiskit.dagcircuit.DAGDepNode(type=None, op=None, name=None, qargs=(), cargs=(), successors=None, predecessors=None, reachable=None, matchedwith=None, successorstovisit=None, isblocked=None, qindices=None, cindices=None, nid=-1)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagdepnode.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDependency.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDependency.md index 279164a403a..45bf6e684ec 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDependency.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGDependency.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGDependency -`qiskit.dagcircuit.DAGDependency`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagdependency.py "view source code") +`qiskit.dagcircuit.DAGDependency`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagdependency.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGInNode.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGInNode.md index 6b52eef5f61..82d9e2d341f 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGInNode.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGInNode.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGInNode -`qiskit.dagcircuit.DAGInNode(wire)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagnode.py "view source code") +`qiskit.dagcircuit.DAGInNode(wire)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagnode.py "view source code") Bases: [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.dagnode.DAGNode") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGNode.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGNode.md index b6daae6f007..b1ac3f19330 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGNode.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGNode.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGNode -`qiskit.dagcircuit.DAGNode(nid=-1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagnode.py "view source code") +`qiskit.dagcircuit.DAGNode(nid=-1)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagnode.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOpNode.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOpNode.md index 5b60f04bac6..cc3ba69fd78 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOpNode.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOpNode.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGOpNode -`qiskit.dagcircuit.DAGOpNode(op, qargs=(), cargs=(), dag=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagnode.py "view source code") +`qiskit.dagcircuit.DAGOpNode(op, qargs=(), cargs=(), dag=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagnode.py "view source code") Bases: [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.dagnode.DAGNode") diff --git a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOutNode.md b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOutNode.md index 9b745e7697b..df9a8d2fe83 100644 --- a/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOutNode.md +++ b/docs/api/qiskit/dev/qiskit.dagcircuit.DAGOutNode.md @@ -10,7 +10,7 @@ python_api_name: qiskit.dagcircuit.DAGOutNode -`qiskit.dagcircuit.DAGOutNode(wire)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/dagcircuit/dagnode.py "view source code") +`qiskit.dagcircuit.DAGOutNode(wire)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/dagcircuit/dagnode.py "view source code") Bases: [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.dagnode.DAGNode") diff --git a/docs/api/qiskit/dev/qiskit.passmanager.BaseController.md b/docs/api/qiskit/dev/qiskit.passmanager.BaseController.md index 4e0308c38ef..285388ec928 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.BaseController.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.BaseController.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.BaseController -`qiskit.passmanager.BaseController(options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/base_tasks.py "view source code") +`qiskit.passmanager.BaseController(options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/base_tasks.py "view source code") Bases: `Task`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") @@ -36,9 +36,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -46,7 +46,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### iter\_tasks @@ -60,7 +60,7 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Parameters** -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. * **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. **Yields** @@ -69,5 +69,5 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Return type** -Generator\[Task, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState"), None] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] diff --git a/docs/api/qiskit/dev/qiskit.passmanager.BasePassManager.md b/docs/api/qiskit/dev/qiskit.passmanager.BasePassManager.md index 8a60389e62e..7fa64810010 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.BasePassManager.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.BasePassManager.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.BasePassManager -`qiskit.passmanager.BasePassManager(tasks=(), max_iteration=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/passmanager.py "view source code") +`qiskit.passmanager.BasePassManager(tasks=(), max_iteration=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/passmanager.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.passmanager.ConditionalController.md b/docs/api/qiskit/dev/qiskit.passmanager.ConditionalController.md index ad4ad770b1d..671a4435499 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.ConditionalController.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.ConditionalController.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.ConditionalController -`qiskit.passmanager.ConditionalController(tasks=(), condition=None, *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/flow_controllers.py "view source code") +`qiskit.passmanager.ConditionalController(tasks=(), condition=None, *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/flow_controllers.py "view source code") Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") @@ -42,9 +42,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -52,7 +52,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### iter\_tasks @@ -66,7 +66,7 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Parameters** -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. * **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. **Yields** @@ -75,5 +75,5 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Return type** -Generator\[Task, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState"), None] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] diff --git a/docs/api/qiskit/dev/qiskit.passmanager.DoWhileController.md b/docs/api/qiskit/dev/qiskit.passmanager.DoWhileController.md index a8cb9671eff..6502473539e 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.DoWhileController.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.DoWhileController.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.DoWhileController -`qiskit.passmanager.DoWhileController(tasks=(), do_while=None, *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/flow_controllers.py "view source code") +`qiskit.passmanager.DoWhileController(tasks=(), do_while=None, *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/flow_controllers.py "view source code") Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") @@ -44,9 +44,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -54,7 +54,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### iter\_tasks @@ -68,7 +68,7 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Parameters** -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. * **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. **Yields** @@ -77,5 +77,5 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Return type** -Generator\[Task, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState"), None] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] diff --git a/docs/api/qiskit/dev/qiskit.passmanager.FlowControllerLinear.md b/docs/api/qiskit/dev/qiskit.passmanager.FlowControllerLinear.md index fd8fb0095b1..f14ce15f88d 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.FlowControllerLinear.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.FlowControllerLinear.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.FlowControllerLinear -`qiskit.passmanager.FlowControllerLinear(tasks=(), *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/flow_controllers.py "view source code") +`qiskit.passmanager.FlowControllerLinear(tasks=(), *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/flow_controllers.py "view source code") Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") @@ -42,9 +42,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -52,7 +52,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### iter\_tasks @@ -66,7 +66,7 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Parameters** -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. * **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. **Yields** @@ -75,5 +75,5 @@ Controller subclass can consume the state to build a proper task pipeline. The u **Return type** -Generator\[Task, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState"), None] +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] diff --git a/docs/api/qiskit/dev/qiskit.passmanager.GenericPass.md b/docs/api/qiskit/dev/qiskit.passmanager.GenericPass.md index a47de29c7ce..d6e8fa0c447 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.GenericPass.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.GenericPass.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.GenericPass -`qiskit.passmanager.GenericPass`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/base_tasks.py "view source code") +`qiskit.passmanager.GenericPass`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/base_tasks.py "view source code") Bases: `Task`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") @@ -30,9 +30,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -40,7 +40,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.passmanager.PassManagerState.md b/docs/api/qiskit/dev/qiskit.passmanager.PassManagerState.md index c8816bf37e3..a8d0b36afa6 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.PassManagerState.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.PassManagerState.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.PassManagerState -`qiskit.passmanager.PassManagerState(workflow_status, property_set)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/compilation_status.py "view source code") +`qiskit.passmanager.PassManagerState(workflow_status, property_set)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/compilation_status.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.passmanager.PropertySet.md b/docs/api/qiskit/dev/qiskit.passmanager.PropertySet.md index 21e7762b8ea..ed26e3a3a33 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.PropertySet.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.PropertySet.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.PropertySet -`qiskit.passmanager.PropertySet`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/compilation_status.py "view source code") +`qiskit.passmanager.PropertySet`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/compilation_status.py "view source code") Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") @@ -64,7 +64,7 @@ Return the value for key if key is in the dictionary, else default. `pop(k[, d]) → v, remove specified key and return the corresponding value.` -If key is not found, d is returned if given, otherwise KeyError is raised +If key is not found, default is returned if given, otherwise KeyError is raised ### popitem diff --git a/docs/api/qiskit/dev/qiskit.passmanager.WorkflowStatus.md b/docs/api/qiskit/dev/qiskit.passmanager.WorkflowStatus.md index de38212c4aa..f534e271a02 100644 --- a/docs/api/qiskit/dev/qiskit.passmanager.WorkflowStatus.md +++ b/docs/api/qiskit/dev/qiskit.passmanager.WorkflowStatus.md @@ -10,7 +10,7 @@ python_api_name: qiskit.passmanager.WorkflowStatus -`qiskit.passmanager.WorkflowStatus(count=0, completed_passes=, previous_run=RunState.FAIL)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/passmanager/compilation_status.py "view source code") +`qiskit.passmanager.WorkflowStatus(count=0, completed_passes=, previous_run=RunState.FAIL)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/passmanager/compilation_status.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.primitives.BackendEstimator.md b/docs/api/qiskit/dev/qiskit.primitives.BackendEstimator.md index 9dc13b04ab0..25b3e16b942 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.BackendEstimator.md +++ b/docs/api/qiskit/dev/qiskit.primitives.BackendEstimator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.BackendEstimator -`qiskit.primitives.BackendEstimator(backend, options=None, abelian_grouping=True, bound_pass_manager=None, skip_transpilation=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/backend_estimator.py "view source code") +`qiskit.primitives.BackendEstimator(backend, options=None, abelian_grouping=True, bound_pass_manager=None, skip_transpilation=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/backend_estimator.py "view source code") Bases: `BaseEstimatorV1`\[`PrimitiveJob`\[[`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.base.estimator_result.EstimatorResult")]] @@ -22,11 +22,11 @@ Initialize a new BackendEstimator instance **Parameters** -* **backend** – Required: the backend to run the primitive on -* **options** – Default options. -* **abelian\_grouping** – Whether the observable should be grouped into commuting -* **bound\_pass\_manager** – An optional pass manager to run after parameter binding. -* **skip\_transpilation** – If this is set to True the internal compilation of the input circuits is skipped and the circuit objects will be directly executed when this object is called. +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.BackendV2")) – Required: the backend to run the primitive on +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. +* **abelian\_grouping** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the observable should be grouped into commuting +* **bound\_pass\_manager** ([*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") *| None*) – An optional pass manager to run after parameter binding. +* **skip\_transpilation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If this is set to True the internal compilation of the input circuits is skipped and the circuit objects will be directly executed when this object is called. ## Attributes diff --git a/docs/api/qiskit/dev/qiskit.primitives.BackendSampler.md b/docs/api/qiskit/dev/qiskit.primitives.BackendSampler.md index 807e3f1ac6d..c2c1253eb55 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.BackendSampler.md +++ b/docs/api/qiskit/dev/qiskit.primitives.BackendSampler.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.BackendSampler -`qiskit.primitives.BackendSampler(backend, options=None, bound_pass_manager=None, skip_transpilation=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/backend_sampler.py "view source code") +`qiskit.primitives.BackendSampler(backend, options=None, bound_pass_manager=None, skip_transpilation=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/backend_sampler.py "view source code") Bases: `BaseSamplerV1`\[`PrimitiveJob`\[[`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.base.sampler_result.SamplerResult")]] @@ -22,10 +22,10 @@ Initialize a new BackendSampler **Parameters** -* **backend** – Required: the backend to run the sampler primitive on -* **options** – Default options. -* **bound\_pass\_manager** – An optional pass manager to run after parameter binding. -* **skip\_transpilation** – If this is set to True the internal compilation of the input circuits is skipped and the circuit objects will be directly executed when this objected is called. +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.BackendV2")) – Required: the backend to run the sampler primitive on +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. +* **bound\_pass\_manager** ([*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") *| None*) – An optional pass manager to run after parameter binding. +* **skip\_transpilation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If this is set to True the internal compilation of the input circuits is skipped and the circuit objects will be directly executed when this objected is called. **Raises** diff --git a/docs/api/qiskit/dev/qiskit.primitives.BaseEstimatorV2.md b/docs/api/qiskit/dev/qiskit.primitives.BaseEstimatorV2.md index 80961a152e5..a9199a237bf 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.BaseEstimatorV2.md +++ b/docs/api/qiskit/dev/qiskit.primitives.BaseEstimatorV2.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.BaseEstimatorV2 -`qiskit.primitives.BaseEstimatorV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/base/base_estimator.py "view source code") +`qiskit.primitives.BaseEstimatorV2`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/base/base_estimator.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.primitives.BaseSamplerV2.md b/docs/api/qiskit/dev/qiskit.primitives.BaseSamplerV2.md index 4d1da9b3f6a..ef363f22819 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.BaseSamplerV2.md +++ b/docs/api/qiskit/dev/qiskit.primitives.BaseSamplerV2.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.BaseSamplerV2 -`qiskit.primitives.BaseSamplerV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/base/base_sampler.py "view source code") +`qiskit.primitives.BaseSamplerV2`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/base/base_sampler.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.primitives.Estimator.md b/docs/api/qiskit/dev/qiskit.primitives.Estimator.md index 752b4b6e440..9fcdab59bcd 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.Estimator.md +++ b/docs/api/qiskit/dev/qiskit.primitives.Estimator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.Estimator -`qiskit.primitives.Estimator(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/estimator.py "view source code") +`qiskit.primitives.Estimator(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/estimator.py "view source code") Bases: `BaseEstimatorV1`\[`PrimitiveJob`\[[`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.base.estimator_result.EstimatorResult")]] @@ -23,7 +23,7 @@ Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator#qi **Parameters** -**options** – Default options. +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. **Raises** diff --git a/docs/api/qiskit/dev/qiskit.primitives.EstimatorResult.md b/docs/api/qiskit/dev/qiskit.primitives.EstimatorResult.md index 0fe28511a1e..4d4c8893254 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.EstimatorResult.md +++ b/docs/api/qiskit/dev/qiskit.primitives.EstimatorResult.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.EstimatorResult -`qiskit.primitives.EstimatorResult(values, metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/base/estimator_result.py "view source code") +`qiskit.primitives.EstimatorResult(values, metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/base/estimator_result.py "view source code") Bases: `_BasePrimitiveResult` diff --git a/docs/api/qiskit/dev/qiskit.primitives.PrimitiveResult.md b/docs/api/qiskit/dev/qiskit.primitives.PrimitiveResult.md index 476ac20f63a..32f17758ce8 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.PrimitiveResult.md +++ b/docs/api/qiskit/dev/qiskit.primitives.PrimitiveResult.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.PrimitiveResult -`qiskit.primitives.PrimitiveResult(pub_results, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/containers/primitive_result.py "view source code") +`qiskit.primitives.PrimitiveResult(pub_results, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/containers/primitive_result.py "view source code") Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic "(in Python v3.12)")\[`T`] @@ -18,8 +18,8 @@ A container for multiple pub results and global metadata. **Parameters** -* **pub\_results** – Pub results. -* **metadata** – Metadata that is common to all pub results; metadata specific to particular pubs should be placed in their metadata fields. Keys are expected to be strings. +* **pub\_results** (*Iterable\[T]*) – Pub results. +* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – Metadata that is common to all pub results; metadata specific to particular pubs should be placed in their metadata fields. Keys are expected to be strings. ## Attributes diff --git a/docs/api/qiskit/dev/qiskit.primitives.PubResult.md b/docs/api/qiskit/dev/qiskit.primitives.PubResult.md index 2c6d8f2e645..a543fbb972b 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.PubResult.md +++ b/docs/api/qiskit/dev/qiskit.primitives.PubResult.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.PubResult -`qiskit.primitives.PubResult(data, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/containers/pub_result.py "view source code") +`qiskit.primitives.PubResult(data, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/containers/pub_result.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.primitives.Sampler.md b/docs/api/qiskit/dev/qiskit.primitives.Sampler.md index 112db62ee7e..5c387088881 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.Sampler.md +++ b/docs/api/qiskit/dev/qiskit.primitives.Sampler.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.Sampler -`qiskit.primitives.Sampler(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/sampler.py "view source code") +`qiskit.primitives.Sampler(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/sampler.py "view source code") Bases: `BaseSamplerV1`\[`PrimitiveJob`\[[`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.base.sampler_result.SamplerResult")]] @@ -25,7 +25,7 @@ Sampler class. **Parameters** -**options** – Default options. +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. **Raises** diff --git a/docs/api/qiskit/dev/qiskit.primitives.SamplerResult.md b/docs/api/qiskit/dev/qiskit.primitives.SamplerResult.md index c650b1d161b..c759ae9f23c 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.SamplerResult.md +++ b/docs/api/qiskit/dev/qiskit.primitives.SamplerResult.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.SamplerResult -`qiskit.primitives.SamplerResult(quasi_dists, metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/base/sampler_result.py "view source code") +`qiskit.primitives.SamplerResult(quasi_dists, metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/base/sampler_result.py "view source code") Bases: `_BasePrimitiveResult` @@ -33,7 +33,7 @@ where the i-th elements of `result` correspond to the circuit given by `circuits ### quasi\_dists -`list[QuasiDistribution]` +`list[qiskit.result.distributions.quasi.QuasiDistribution]` diff --git a/docs/api/qiskit/dev/qiskit.primitives.StatevectorEstimator.md b/docs/api/qiskit/dev/qiskit.primitives.StatevectorEstimator.md index 1fc1ff24f88..cb2f30d60db 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.StatevectorEstimator.md +++ b/docs/api/qiskit/dev/qiskit.primitives.StatevectorEstimator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.StatevectorEstimator -`qiskit.primitives.StatevectorEstimator(*, default_precision=0.0, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/statevector_estimator.py "view source code") +`qiskit.primitives.StatevectorEstimator(*, default_precision=0.0, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/statevector_estimator.py "view source code") Bases: [`BaseEstimatorV2`](qiskit.primitives.BaseEstimatorV2 "qiskit.primitives.base.base_estimator.BaseEstimatorV2") diff --git a/docs/api/qiskit/dev/qiskit.primitives.StatevectorSampler.md b/docs/api/qiskit/dev/qiskit.primitives.StatevectorSampler.md index db08e0cd4b0..20ed51d0735 100644 --- a/docs/api/qiskit/dev/qiskit.primitives.StatevectorSampler.md +++ b/docs/api/qiskit/dev/qiskit.primitives.StatevectorSampler.md @@ -10,7 +10,7 @@ python_api_name: qiskit.primitives.StatevectorSampler -`qiskit.primitives.StatevectorSampler(*, default_shots=1024, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/primitives/statevector_sampler.py "view source code") +`qiskit.primitives.StatevectorSampler(*, default_shots=1024, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/primitives/statevector_sampler.py "view source code") Bases: [`BaseSamplerV2`](qiskit.primitives.BaseSamplerV2 "qiskit.primitives.base.base_sampler.BaseSamplerV2") diff --git a/docs/api/qiskit/dev/qiskit.providers.Backend.md b/docs/api/qiskit/dev/qiskit.providers.Backend.md index 7d2d594433b..db363e1ff1b 100644 --- a/docs/api/qiskit/dev/qiskit.providers.Backend.md +++ b/docs/api/qiskit/dev/qiskit.providers.Backend.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.Backend -`qiskit.providers.Backend`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/backend.py "view source code") +`qiskit.providers.Backend`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/backend.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.BackendV1.md b/docs/api/qiskit/dev/qiskit.providers.BackendV1.md index d2defaa57c1..59bc0dfaba8 100644 --- a/docs/api/qiskit/dev/qiskit.providers.BackendV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.BackendV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.BackendV1 -`qiskit.providers.BackendV1(configuration, provider=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/backend.py "view source code") +`qiskit.providers.BackendV1(configuration, provider=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/backend.py "view source code") Bases: [`Backend`](qiskit.providers.Backend "qiskit.providers.backend.Backend"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.BackendV2.md b/docs/api/qiskit/dev/qiskit.providers.BackendV2.md index cce9d45ce57..1e4630f635e 100644 --- a/docs/api/qiskit/dev/qiskit.providers.BackendV2.md +++ b/docs/api/qiskit/dev/qiskit.providers.BackendV2.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.BackendV2 -`qiskit.providers.BackendV2(provider=None, name=None, description=None, online_date=None, backend_version=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/backend.py "view source code") +`qiskit.providers.BackendV2(provider=None, name=None, description=None, online_date=None, backend_version=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/backend.py "view source code") Bases: [`Backend`](qiskit.providers.Backend "qiskit.providers.backend.Backend"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.BackendV2Converter.md b/docs/api/qiskit/dev/qiskit.providers.BackendV2Converter.md index ec4c6c3be22..74cf875a40d 100644 --- a/docs/api/qiskit/dev/qiskit.providers.BackendV2Converter.md +++ b/docs/api/qiskit/dev/qiskit.providers.BackendV2Converter.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.BackendV2Converter -`qiskit.providers.BackendV2Converter(backend, name_mapping=None, add_delay=True, filter_faulty=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/backend_compat.py "view source code") +`qiskit.providers.BackendV2Converter(backend, name_mapping=None, add_delay=True, filter_faulty=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/backend_compat.py "view source code") Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") diff --git a/docs/api/qiskit/dev/qiskit.providers.Job.md b/docs/api/qiskit/dev/qiskit.providers.Job.md index 2ab509e4709..d3e16236ea8 100644 --- a/docs/api/qiskit/dev/qiskit.providers.Job.md +++ b/docs/api/qiskit/dev/qiskit.providers.Job.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.Job -`qiskit.providers.Job`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/job.py "view source code") +`qiskit.providers.Job`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/job.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.JobStatus.md b/docs/api/qiskit/dev/qiskit.providers.JobStatus.md index 32343d91933..0e55569d627 100644 --- a/docs/api/qiskit/dev/qiskit.providers.JobStatus.md +++ b/docs/api/qiskit/dev/qiskit.providers.JobStatus.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.JobStatus -`qiskit.providers.JobStatus(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/jobstatus.py "view source code") +`qiskit.providers.JobStatus(value)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/jobstatus.py "view source code") Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.JobV1.md b/docs/api/qiskit/dev/qiskit.providers.JobV1.md index bf0e70297ec..5241a284634 100644 --- a/docs/api/qiskit/dev/qiskit.providers.JobV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.JobV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.JobV1 -`qiskit.providers.JobV1(backend, job_id, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/job.py "view source code") +`qiskit.providers.JobV1(backend, job_id, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/job.py "view source code") Bases: [`Job`](qiskit.providers.Job "qiskit.providers.job.Job"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.Options.md b/docs/api/qiskit/dev/qiskit.providers.Options.md index d2a953db282..65df1c01cdd 100644 --- a/docs/api/qiskit/dev/qiskit.providers.Options.md +++ b/docs/api/qiskit/dev/qiskit.providers.Options.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.Options -`qiskit.providers.Options(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/options.py "view source code") +`qiskit.providers.Options(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/options.py "view source code") Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.Provider.md b/docs/api/qiskit/dev/qiskit.providers.Provider.md index c0d30d2319a..36ac6917787 100644 --- a/docs/api/qiskit/dev/qiskit.providers.Provider.md +++ b/docs/api/qiskit/dev/qiskit.providers.Provider.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.Provider -`qiskit.providers.Provider`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/provider.py "view source code") +`qiskit.providers.Provider`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/provider.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.ProviderV1.md b/docs/api/qiskit/dev/qiskit.providers.ProviderV1.md index a9f930d9ac4..62f4150e1e2 100644 --- a/docs/api/qiskit/dev/qiskit.providers.ProviderV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.ProviderV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.ProviderV1 -`qiskit.providers.ProviderV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/provider.py "view source code") +`qiskit.providers.ProviderV1`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/provider.py "view source code") Bases: [`Provider`](qiskit.providers.Provider "qiskit.providers.provider.Provider"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.QubitProperties.md b/docs/api/qiskit/dev/qiskit.providers.QubitProperties.md index f57eb83fb05..39c1b15f650 100644 --- a/docs/api/qiskit/dev/qiskit.providers.QubitProperties.md +++ b/docs/api/qiskit/dev/qiskit.providers.QubitProperties.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.QubitProperties -`qiskit.providers.QubitProperties(t1=None, t2=None, frequency=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/backend.py "view source code") +`qiskit.providers.QubitProperties(t1=None, t2=None, frequency=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/backend.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProvider.md b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProvider.md index 00921081ff7..61b6f0fe0da 100644 --- a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProvider.md +++ b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProvider.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.basic_provider.BasicProvider -`qiskit.providers.basic_provider.BasicProvider`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/basic_provider/basic_provider.py "view source code") +`qiskit.providers.basic_provider.BasicProvider`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/basic_provider/basic_provider.py "view source code") Bases: [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.provider.ProviderV1") diff --git a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderError.md b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderError.md index 45cc7f0d2f5..4c0835033fb 100644 --- a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderError.md +++ b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderError.md @@ -12,7 +12,7 @@ python_api_name: qiskit.providers.basic_provider.BasicProviderError -`qiskit.providers.basic_provider.BasicProviderError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/basic_provider/exceptions.py "view source code") +`qiskit.providers.basic_provider.BasicProviderError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/basic_provider/exceptions.py "view source code") Base class for errors raised by the Basic Provider. diff --git a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderJob.md b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderJob.md index dfaf1a1966a..9262d483c20 100644 --- a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderJob.md +++ b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicProviderJob.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.basic_provider.BasicProviderJob -`qiskit.providers.basic_provider.BasicProviderJob(backend, job_id, result)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/basic_provider/basic_provider_job.py "view source code") +`qiskit.providers.basic_provider.BasicProviderJob(backend, job_id, result)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/basic_provider/basic_provider_job.py "view source code") Bases: [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.job.JobV1") diff --git a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicSimulator.md b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicSimulator.md index 335ea09d7b9..87bf63e125f 100644 --- a/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicSimulator.md +++ b/docs/api/qiskit/dev/qiskit.providers.basic_provider.BasicSimulator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.basic_provider.BasicSimulator -`qiskit.providers.basic_provider.BasicSimulator(provider=None, target=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/basic_provider/basic_simulator.py "view source code") +`qiskit.providers.basic_provider.BasicSimulator(provider=None, target=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/basic_provider/basic_simulator.py "view source code") Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") @@ -363,7 +363,7 @@ Run an experiment (circuit) and return a single experiment result. **Parameters** -**experiment** ([*QasmQobjExperiment*](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment")) – experiment from qobj experiments list +**experiment** ([*QasmQobjExperiment*](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.qasm_qobj.QasmQobjExperiment")) – experiment from qobj experiments list **Returns** diff --git a/docs/api/qiskit/dev/qiskit.providers.convert_to_target.md b/docs/api/qiskit/dev/qiskit.providers.convert_to_target.md index ea4a5a015b6..89a78c0219b 100644 --- a/docs/api/qiskit/dev/qiskit.providers.convert_to_target.md +++ b/docs/api/qiskit/dev/qiskit.providers.convert_to_target.md @@ -12,7 +12,7 @@ python_api_name: qiskit.providers.convert_to_target -`qiskit.providers.convert_to_target(configuration, properties=None, defaults=None, custom_name_mapping=None, add_delay=True, filter_faulty=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/backend_compat.py "view source code") +`qiskit.providers.convert_to_target(configuration, properties=None, defaults=None, custom_name_mapping=None, add_delay=True, filter_faulty=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/backend_compat.py "view source code") Decode transpiler target from backend data set. diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake127QPulseV1.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake127QPulseV1.md index 72354569ae9..15eabfdd54a 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake127QPulseV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake127QPulseV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.Fake127QPulseV1 -`qiskit.providers.fake_provider.Fake127QPulseV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/backends_v1/fake_127q_pulse/fake_127q_pulse_v1.py "view source code") +`qiskit.providers.fake_provider.Fake127QPulseV1`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/backends_v1/fake_127q_pulse/fake_127q_pulse_v1.py "view source code") Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") @@ -57,7 +57,7 @@ FakeBackend initializer. ### dirname -`= '/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/qiskit/providers/fake_provider/backends_v1/fake_127q_pulse'` +`= '/home/runner/work/qiskit/qiskit/.tox/docs/lib/python3.9/site-packages/qiskit/providers/fake_provider/backends_v1/fake_127q_pulse'` diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake1Q.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake1Q.md index 34151f1410a..9f7c2672cd6 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake1Q.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake1Q.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.Fake1Q -`qiskit.providers.fake_provider.Fake1Q`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/fake_1q.py "view source code") +`qiskit.providers.fake_provider.Fake1Q`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/fake_1q.py "view source code") Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake20QV1.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake20QV1.md index 82bebc8c435..d93a10104bc 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake20QV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake20QV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.Fake20QV1 -`qiskit.providers.fake_provider.Fake20QV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/backends_v1/fake_20q/fake_20q.py "view source code") +`qiskit.providers.fake_provider.Fake20QV1`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/backends_v1/fake_20q/fake_20q.py "view source code") Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") @@ -57,7 +57,7 @@ FakeBackend initializer. ### dirname -`= '/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/qiskit/providers/fake_provider/backends_v1/fake_20q'` +`= '/home/runner/work/qiskit/qiskit/.tox/docs/lib/python3.9/site-packages/qiskit/providers/fake_provider/backends_v1/fake_20q'` diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake27QPulseV1.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake27QPulseV1.md index 3705c503212..4be8d74d812 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake27QPulseV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake27QPulseV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.Fake27QPulseV1 -`qiskit.providers.fake_provider.Fake27QPulseV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/backends_v1/fake_27q_pulse/fake_27q_pulse_v1.py "view source code") +`qiskit.providers.fake_provider.Fake27QPulseV1`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/backends_v1/fake_27q_pulse/fake_27q_pulse_v1.py "view source code") Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") @@ -69,7 +69,7 @@ FakeBackend initializer. ### dirname -`= '/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/qiskit/providers/fake_provider/backends_v1/fake_27q_pulse'` +`= '/home/runner/work/qiskit/qiskit/.tox/docs/lib/python3.9/site-packages/qiskit/providers/fake_provider/backends_v1/fake_27q_pulse'` diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake5QV1.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake5QV1.md index 3aaa9156d8a..0eda3efbb5d 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake5QV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake5QV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.Fake5QV1 -`qiskit.providers.fake_provider.Fake5QV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/backends_v1/fake_5q/fake_5q_v1.py "view source code") +`qiskit.providers.fake_provider.Fake5QV1`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/backends_v1/fake_5q/fake_5q_v1.py "view source code") Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") @@ -55,7 +55,7 @@ FakeBackend initializer. ### dirname -`= '/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/qiskit/providers/fake_provider/backends_v1/fake_5q'` +`= '/home/runner/work/qiskit/qiskit/.tox/docs/lib/python3.9/site-packages/qiskit/providers/fake_provider/backends_v1/fake_5q'` diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake7QPulseV1.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake7QPulseV1.md index 363ed77e7ea..5b53f64f82a 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake7QPulseV1.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.Fake7QPulseV1.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.Fake7QPulseV1 -`qiskit.providers.fake_provider.Fake7QPulseV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/backends_v1/fake_7q_pulse/fake_7q_pulse_v1.py "view source code") +`qiskit.providers.fake_provider.Fake7QPulseV1`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/backends_v1/fake_7q_pulse/fake_7q_pulse_v1.py "view source code") Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") @@ -63,7 +63,7 @@ FakeBackend initializer. ### dirname -`= '/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/qiskit/providers/fake_provider/backends_v1/fake_7q_pulse'` +`= '/home/runner/work/qiskit/qiskit/.tox/docs/lib/python3.9/site-packages/qiskit/providers/fake_provider/backends_v1/fake_7q_pulse'` diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse2Q.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse2Q.md index 98933f30ece..71cb902d374 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse2Q.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse2Q.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.FakeOpenPulse2Q -`qiskit.providers.fake_provider.FakeOpenPulse2Q`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/fake_openpulse_2q.py "view source code") +`qiskit.providers.fake_provider.FakeOpenPulse2Q`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/fake_openpulse_2q.py "view source code") Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse3Q.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse3Q.md index 1cecdf7b69a..bb58320f345 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse3Q.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.FakeOpenPulse3Q.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.FakeOpenPulse3Q -`qiskit.providers.fake_provider.FakeOpenPulse3Q`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/fake_openpulse_3q.py "view source code") +`qiskit.providers.fake_provider.FakeOpenPulse3Q`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/fake_openpulse_3q.py "view source code") Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") diff --git a/docs/api/qiskit/dev/qiskit.providers.fake_provider.GenericBackendV2.md b/docs/api/qiskit/dev/qiskit.providers.fake_provider.GenericBackendV2.md index 8e41da45639..3551f8fd189 100644 --- a/docs/api/qiskit/dev/qiskit.providers.fake_provider.GenericBackendV2.md +++ b/docs/api/qiskit/dev/qiskit.providers.fake_provider.GenericBackendV2.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.fake_provider.GenericBackendV2 -`qiskit.providers.fake_provider.GenericBackendV2(num_qubits, basis_gates=None, *, coupling_map=None, control_flow=False, calibrate_instructions=None, dtm=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/fake_provider/generic_backend_v2.py "view source code") +`qiskit.providers.fake_provider.GenericBackendV2(num_qubits, basis_gates=None, *, coupling_map=None, control_flow=False, calibrate_instructions=None, dtm=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/fake_provider/generic_backend_v2.py "view source code") Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") @@ -219,7 +219,7 @@ This is required to be implemented if the backend supports Pulse scheduling. **Parameters** -**qubits** (*Iterable\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. +**qubits** ([*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. **Returns** diff --git a/docs/api/qiskit/dev/qiskit.providers.models.BackendConfiguration.md b/docs/api/qiskit/dev/qiskit.providers.models.BackendConfiguration.md index 9dc841eaa88..39712dc2ea0 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.BackendConfiguration.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.BackendConfiguration.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.BackendConfiguration -`qiskit.providers.models.BackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, supported_instructions=None, dynamic_reprate_enabled=False, rep_delay_range=None, default_rep_delay=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, dt=None, dtm=None, processor_type=None, parametric_pulses=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendconfiguration.py "view source code") +`qiskit.providers.models.BackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, supported_instructions=None, dynamic_reprate_enabled=False, rep_delay_range=None, default_rep_delay=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, dt=None, dtm=None, processor_type=None, parametric_pulses=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendconfiguration.py "view source code") Bases: [`QasmBackendConfiguration`](qiskit.providers.models.QasmBackendConfiguration "qiskit.providers.models.backendconfiguration.QasmBackendConfiguration") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.BackendProperties.md b/docs/api/qiskit/dev/qiskit.providers.models.BackendProperties.md index 88562a63874..3c032e3620c 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.BackendProperties.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.BackendProperties.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.BackendProperties -`qiskit.providers.models.BackendProperties(backend_name, backend_version, last_update_date, qubits, gates, general, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendproperties.py "view source code") +`qiskit.providers.models.BackendProperties(backend_name, backend_version, last_update_date, qubits, gates, general, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendproperties.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.BackendStatus.md b/docs/api/qiskit/dev/qiskit.providers.models.BackendStatus.md index e80f8392941..5675261b8fe 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.BackendStatus.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.BackendStatus.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.BackendStatus -`qiskit.providers.models.BackendStatus(backend_name, backend_version, operational, pending_jobs, status_msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendstatus.py "view source code") +`qiskit.providers.models.BackendStatus(backend_name, backend_version, operational, pending_jobs, status_msg)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendstatus.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.Command.md b/docs/api/qiskit/dev/qiskit.providers.models.Command.md index 1be4b0e372d..5ca71c6342e 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.Command.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.Command.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.Command -`qiskit.providers.models.Command(name, qubits=None, sequence=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/pulsedefaults.py "view source code") +`qiskit.providers.models.Command(name, qubits=None, sequence=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/pulsedefaults.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.GateConfig.md b/docs/api/qiskit/dev/qiskit.providers.models.GateConfig.md index 54c2d7efe37..87d01e2fa18 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.GateConfig.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.GateConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.GateConfig -`qiskit.providers.models.GateConfig(name, parameters, qasm_def, coupling_map=None, latency_map=None, conditional=None, description=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendconfiguration.py "view source code") +`qiskit.providers.models.GateConfig(name, parameters, qasm_def, coupling_map=None, latency_map=None, conditional=None, description=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendconfiguration.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.GateProperties.md b/docs/api/qiskit/dev/qiskit.providers.models.GateProperties.md index af63a157802..2e010451ff0 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.GateProperties.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.GateProperties.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.GateProperties -`qiskit.providers.models.GateProperties(qubits, gate, parameters, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendproperties.py "view source code") +`qiskit.providers.models.GateProperties(qubits, gate, parameters, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendproperties.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.JobStatus.md b/docs/api/qiskit/dev/qiskit.providers.models.JobStatus.md index 68cd9bb92d6..cbd08c93d1d 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.JobStatus.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.JobStatus.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.JobStatus -`qiskit.providers.models.JobStatus(job_id, status, status_msg, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/jobstatus.py "view source code") +`qiskit.providers.models.JobStatus(job_id, status, status_msg, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/jobstatus.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.Nduv.md b/docs/api/qiskit/dev/qiskit.providers.models.Nduv.md index 443decce647..acdd74378f0 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.Nduv.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.Nduv.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.Nduv -`qiskit.providers.models.Nduv(date, name, unit, value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendproperties.py "view source code") +`qiskit.providers.models.Nduv(date, name, unit, value)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendproperties.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.PulseBackendConfiguration.md b/docs/api/qiskit/dev/qiskit.providers.models.PulseBackendConfiguration.md index d3acf21c910..67ce58adbd3 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.PulseBackendConfiguration.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.PulseBackendConfiguration.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.PulseBackendConfiguration -`qiskit.providers.models.PulseBackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, n_uchannels, u_channel_lo, meas_levels, qubit_lo_range, meas_lo_range, dt, dtm, rep_times, meas_kernels, discriminators, hamiltonian=None, channel_bandwidth=None, acquisition_latency=None, conditional_latency=None, meas_map=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, channels=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendconfiguration.py "view source code") +`qiskit.providers.models.PulseBackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, n_uchannels, u_channel_lo, meas_levels, qubit_lo_range, meas_lo_range, dt, dtm, rep_times, meas_kernels, discriminators, hamiltonian=None, channel_bandwidth=None, acquisition_latency=None, conditional_latency=None, meas_map=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, channels=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendconfiguration.py "view source code") Bases: [`QasmBackendConfiguration`](qiskit.providers.models.QasmBackendConfiguration "qiskit.providers.models.backendconfiguration.QasmBackendConfiguration") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.PulseDefaults.md b/docs/api/qiskit/dev/qiskit.providers.models.PulseDefaults.md index 1df2638c3c9..ec8dd54c67c 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.PulseDefaults.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.PulseDefaults.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.PulseDefaults -`qiskit.providers.models.PulseDefaults(qubit_freq_est, meas_freq_est, buffer, pulse_library, cmd_def, meas_kernel=None, discriminator=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/pulsedefaults.py "view source code") +`qiskit.providers.models.PulseDefaults(qubit_freq_est, meas_freq_est, buffer, pulse_library, cmd_def, meas_kernel=None, discriminator=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/pulsedefaults.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.QasmBackendConfiguration.md b/docs/api/qiskit/dev/qiskit.providers.models.QasmBackendConfiguration.md index 8ce5eba0f5a..2825948ea57 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.QasmBackendConfiguration.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.QasmBackendConfiguration.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.QasmBackendConfiguration -`qiskit.providers.models.QasmBackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, supported_instructions=None, dynamic_reprate_enabled=False, rep_delay_range=None, default_rep_delay=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, dt=None, dtm=None, processor_type=None, parametric_pulses=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendconfiguration.py "view source code") +`qiskit.providers.models.QasmBackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, supported_instructions=None, dynamic_reprate_enabled=False, rep_delay_range=None, default_rep_delay=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, dt=None, dtm=None, processor_type=None, parametric_pulses=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendconfiguration.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.providers.models.UchannelLO.md b/docs/api/qiskit/dev/qiskit.providers.models.UchannelLO.md index 3c931043ee7..374ca58ce20 100644 --- a/docs/api/qiskit/dev/qiskit.providers.models.UchannelLO.md +++ b/docs/api/qiskit/dev/qiskit.providers.models.UchannelLO.md @@ -10,7 +10,7 @@ python_api_name: qiskit.providers.models.UchannelLO -`qiskit.providers.models.UchannelLO(q, scale)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/providers/models/backendconfiguration.py "view source code") +`qiskit.providers.models.UchannelLO(q, scale)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/providers/models/backendconfiguration.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.pulse.InstructionScheduleMap.md b/docs/api/qiskit/dev/qiskit.pulse.InstructionScheduleMap.md index ea455dff1ab..b550f163c4f 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.InstructionScheduleMap.md +++ b/docs/api/qiskit/dev/qiskit.pulse.InstructionScheduleMap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.InstructionScheduleMap -`qiskit.pulse.InstructionScheduleMap`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instruction_schedule_map.py "view source code") +`qiskit.pulse.InstructionScheduleMap`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instruction_schedule_map.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.pulse.Schedule.md b/docs/api/qiskit/dev/qiskit.pulse.Schedule.md index 3e91f39defb..a88d9f0c722 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.Schedule.md +++ b/docs/api/qiskit/dev/qiskit.pulse.Schedule.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.Schedule -`qiskit.pulse.Schedule(*schedules, name=None, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/schedule.py "view source code") +`qiskit.pulse.Schedule(*schedules, name=None, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/schedule.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") @@ -186,7 +186,7 @@ Assign the parameters in this schedule according to the input. **Parameters** -* **value\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*, ParameterValueType]*) – A mapping from Parameters to either numeric values or another Parameter expression. +* **value\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*qiskit.circuit.parameterexpression.ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*Union*](https://docs.python.org/3/library/typing.html#typing.Union "(in Python v3.12)")*\[*[*qiskit.circuit.parameterexpression.ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – A mapping from Parameters to either numeric values or another Parameter expression. * **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set `True` to override this instance with new parameter. **Returns** @@ -195,7 +195,7 @@ Schedule with updated parameters. **Return type** -[Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule") +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") ### ch\_duration @@ -359,7 +359,7 @@ Parameter objects that have corresponding name. **Return type** -[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Parameter](qiskit.circuit.Parameter "qiskit.circuit.Parameter")] +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.circuit.parameter.Parameter](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")] ### initialize\_from @@ -462,8 +462,8 @@ Only matches at the top-level of the schedule tree. If you wish to perform this **Parameters** -* **old** (*ScheduleComponent*) – Instruction to replace. -* **new** (*ScheduleComponent*) – Instruction to replace with. +* **old** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Instruction to replace. +* **new** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Instruction to replace with. * **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Replace instruction by mutably modifying this `Schedule`. **Returns** @@ -476,7 +476,7 @@ The modified schedule with `old` replaced by `new`. **Return type** -[Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule") +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") ### shift diff --git a/docs/api/qiskit/dev/qiskit.pulse.ScheduleBlock.md b/docs/api/qiskit/dev/qiskit.pulse.ScheduleBlock.md index beafa210c31..fa7d7b81698 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.ScheduleBlock.md +++ b/docs/api/qiskit/dev/qiskit.pulse.ScheduleBlock.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.ScheduleBlock -`qiskit.pulse.ScheduleBlock(name=None, metadata=None, alignment_context=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/schedule.py "view source code") +`qiskit.pulse.ScheduleBlock(name=None, metadata=None, alignment_context=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/schedule.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") @@ -241,7 +241,7 @@ Assign the parameters in this schedule according to the input. **Parameters** -* **value\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*, ParameterValueType]*) – A mapping from Parameters to either numeric values or another Parameter expression. +* **value\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*qiskit.circuit.parameterexpression.ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*Union*](https://docs.python.org/3/library/typing.html#typing.Union "(in Python v3.12)")*\[*[*qiskit.circuit.parameterexpression.ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – A mapping from Parameters to either numeric values or another Parameter expression. * **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set `True` to override this instance with new parameter. **Returns** @@ -254,7 +254,7 @@ Schedule with updated parameters. **Return type** -[ScheduleBlock](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") ### assign\_references @@ -468,7 +468,7 @@ Parameter objects that have corresponding name. **Return type** -[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Parameter](qiskit.circuit.Parameter "qiskit.circuit.Parameter")] +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.circuit.parameter.Parameter](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")] ### initialize\_from @@ -541,8 +541,8 @@ Return a `ScheduleBlock` with the `old` component replaced with a `new` componen **Parameters** -* **old** (*BlockComponent*) – Schedule block component to replace. -* **new** (*BlockComponent*) – Schedule block component to replace with. +* **old** ([*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule block component to replace. +* **new** ([*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule block component to replace with. * **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Replace instruction by mutably modifying this `ScheduleBlock`. **Returns** @@ -551,5 +551,5 @@ The modified schedule block with `old` replaced by `new`. **Return type** -[ScheduleBlock](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.AcquireChannel.md b/docs/api/qiskit/dev/qiskit.pulse.channels.AcquireChannel.md index 963fb687045..5448fdc80a3 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.AcquireChannel.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.AcquireChannel.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.AcquireChannel -`qiskit.pulse.channels.AcquireChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.AcquireChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.ControlChannel.md b/docs/api/qiskit/dev/qiskit.pulse.channels.ControlChannel.md index d79d2a41ef9..108ee3a8684 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.ControlChannel.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.ControlChannel.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.ControlChannel -`qiskit.pulse.channels.ControlChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.ControlChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: `PulseChannel` diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.DriveChannel.md b/docs/api/qiskit/dev/qiskit.pulse.channels.DriveChannel.md index 84be3f57ca0..c7a0859d447 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.DriveChannel.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.DriveChannel.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.DriveChannel -`qiskit.pulse.channels.DriveChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.DriveChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: `PulseChannel` diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.MeasureChannel.md b/docs/api/qiskit/dev/qiskit.pulse.channels.MeasureChannel.md index 8fa1709d19c..a3cd34caae3 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.MeasureChannel.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.MeasureChannel.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.MeasureChannel -`qiskit.pulse.channels.MeasureChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.MeasureChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: `PulseChannel` diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.MemorySlot.md b/docs/api/qiskit/dev/qiskit.pulse.channels.MemorySlot.md index 32cf4d2f147..78ee2ebeb53 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.MemorySlot.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.MemorySlot.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.MemorySlot -`qiskit.pulse.channels.MemorySlot(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.MemorySlot(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: `ClassicalIOChannel` diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.RegisterSlot.md b/docs/api/qiskit/dev/qiskit.pulse.channels.RegisterSlot.md index 24ef077c940..df71644e1e9 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.RegisterSlot.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.RegisterSlot.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.RegisterSlot -`qiskit.pulse.channels.RegisterSlot(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.RegisterSlot(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: `ClassicalIOChannel` diff --git a/docs/api/qiskit/dev/qiskit.pulse.channels.SnapshotChannel.md b/docs/api/qiskit/dev/qiskit.pulse.channels.SnapshotChannel.md index c37756b6a8b..d1b4bc8532e 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.channels.SnapshotChannel.md +++ b/docs/api/qiskit/dev/qiskit.pulse.channels.SnapshotChannel.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.channels.SnapshotChannel -`qiskit.pulse.channels.SnapshotChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/channels.py "view source code") +`qiskit.pulse.channels.SnapshotChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/channels.py "view source code") Bases: `ClassicalIOChannel` diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.Acquire.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.Acquire.md index 8e42b599b6f..29ac6396806 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.Acquire.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.Acquire.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.Acquire -`qiskit.pulse.instructions.Acquire(duration, channel, mem_slot=None, reg_slot=None, kernel=None, discriminator=None, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/acquire.py "view source code") +`qiskit.pulse.instructions.Acquire(duration, channel, mem_slot=None, reg_slot=None, kernel=None, discriminator=None, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/acquire.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.Delay.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.Delay.md index c159ae2429b..32eb2dd47c3 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.Delay.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.Delay.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.Delay -`qiskit.pulse.instructions.Delay(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/delay.py "view source code") +`qiskit.pulse.instructions.Delay(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/delay.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.Play.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.Play.md index c93f76404bb..90a35900567 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.Play.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.Play.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.Play -`qiskit.pulse.instructions.Play(pulse, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/play.py "view source code") +`qiskit.pulse.instructions.Play(pulse, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/play.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.Reference.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.Reference.md index 30300d12bfa..bfcafa3baac 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.Reference.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.Reference.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.Reference -`qiskit.pulse.instructions.Reference(name, *extra_keys)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/reference.py "view source code") +`qiskit.pulse.instructions.Reference(name, *extra_keys)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/reference.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.RelativeBarrier.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.RelativeBarrier.md index 96ca357cc5f..dcfc47dbe35 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.RelativeBarrier.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.RelativeBarrier.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.RelativeBarrier -`qiskit.pulse.instructions.RelativeBarrier(*channels, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/directives.py "view source code") +`qiskit.pulse.instructions.RelativeBarrier(*channels, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/directives.py "view source code") Bases: `Directive` diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.SetFrequency.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.SetFrequency.md index 4441d61074b..658b83fbbf1 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.SetFrequency.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.SetFrequency.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.SetFrequency -`qiskit.pulse.instructions.SetFrequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/frequency.py "view source code") +`qiskit.pulse.instructions.SetFrequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/frequency.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.SetPhase.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.SetPhase.md index ff8725f8f8d..75e562ae499 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.SetPhase.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.SetPhase.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.SetPhase -`qiskit.pulse.instructions.SetPhase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/phase.py "view source code") +`qiskit.pulse.instructions.SetPhase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/phase.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftFrequency.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftFrequency.md index 634f92b7748..9f86e460e7c 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftFrequency.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftFrequency.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.ShiftFrequency -`qiskit.pulse.instructions.ShiftFrequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/frequency.py "view source code") +`qiskit.pulse.instructions.ShiftFrequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/frequency.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftPhase.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftPhase.md index aa80ae519ed..e21e50dcc66 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftPhase.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.ShiftPhase.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.ShiftPhase -`qiskit.pulse.instructions.ShiftPhase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/phase.py "view source code") +`qiskit.pulse.instructions.ShiftPhase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/phase.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.Snapshot.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.Snapshot.md index 6e88b21477e..4e625ffb90c 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.Snapshot.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.Snapshot.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.Snapshot -`qiskit.pulse.instructions.Snapshot(label, snapshot_type='statevector', name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/snapshot.py "view source code") +`qiskit.pulse.instructions.Snapshot(label, snapshot_type='statevector', name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/snapshot.py "view source code") Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") diff --git a/docs/api/qiskit/dev/qiskit.pulse.instructions.TimeBlockade.md b/docs/api/qiskit/dev/qiskit.pulse.instructions.TimeBlockade.md index 51940f5f3af..ddc28fcff28 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.instructions.TimeBlockade.md +++ b/docs/api/qiskit/dev/qiskit.pulse.instructions.TimeBlockade.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.instructions.TimeBlockade -`qiskit.pulse.instructions.TimeBlockade(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/instructions/directives.py "view source code") +`qiskit.pulse.instructions.TimeBlockade(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/instructions/directives.py "view source code") Bases: `Directive` diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Constant_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Constant_class.rst.md index 3f8f8b929f3..eca6d19355c 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Constant_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Constant_class.rst.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.library.Constant -`qiskit.pulse.library.Constant(duration, amp, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Constant(duration, amp, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Cos_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Cos_class.rst.md index 0906017d97c..cbe05b1dd93 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Cos_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Cos_class.rst.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.Cos -`qiskit.pulse.library.Cos(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Cos(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") A cosine pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Drag_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Drag_class.rst.md index 56aee3ad898..a0da4fd4d3a 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Drag_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Drag_class.rst.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.library.Drag -`qiskit.pulse.library.Drag(duration, amp, sigma, beta, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Drag(duration, amp, sigma, beta, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.GaussianDeriv.md b/docs/api/qiskit/dev/qiskit.pulse.library.GaussianDeriv.md index 07efd2966f5..f9ed5090bd1 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.GaussianDeriv.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.GaussianDeriv.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.GaussianDeriv -`qiskit.pulse.library.GaussianDeriv(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.GaussianDeriv(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") An unnormalized Gaussian derivative pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquare.md b/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquare.md index 73eb3056905..85173600bf4 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquare.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquare.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.library.GaussianSquare -`qiskit.pulse.library.GaussianSquare(duration, amp, sigma, width=None, angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.GaussianSquare(duration, amp, sigma, width=None, angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquareDrag.md b/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquareDrag.md index 05b2d41c060..f8f605da444 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquareDrag.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.GaussianSquareDrag.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.GaussianSquareDrag -`qiskit.pulse.library.GaussianSquareDrag(duration, amp, sigma, beta, width=None, angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.GaussianSquareDrag(duration, amp, sigma, beta, width=None, angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") A square pulse with a Drag shaped rise and fall diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Gaussian_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Gaussian_class.rst.md index 062f32c32ce..4afb32f1203 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Gaussian_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Gaussian_class.rst.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.library.Gaussian -`qiskit.pulse.library.Gaussian(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Gaussian(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Sawtooth_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Sawtooth_class.rst.md index feec3ab39c6..f137642b094 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Sawtooth_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Sawtooth_class.rst.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.Sawtooth -`qiskit.pulse.library.Sawtooth(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Sawtooth(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") A sawtooth pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.SechDeriv.md b/docs/api/qiskit/dev/qiskit.pulse.library.SechDeriv.md index 16d2705ea43..0309559678f 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.SechDeriv.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.SechDeriv.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.SechDeriv -`qiskit.pulse.library.SechDeriv(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.SechDeriv(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") An unnormalized sech derivative pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Sech_fun.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Sech_fun.rst.md index 4d47d4d10df..e6a4793994b 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Sech_fun.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Sech_fun.rst.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.Sech -`qiskit.pulse.library.Sech(duration, amp, sigma, angle=0.0, name=None, zero_ends=True, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Sech(duration, amp, sigma, angle=0.0, name=None, zero_ends=True, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") An unnormalized sech pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Sin_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Sin_class.rst.md index ede3090a9a2..e41ec397223 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Sin_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Sin_class.rst.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.Sin -`qiskit.pulse.library.Sin(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Sin(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") A sinusoidal pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Square_fun.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Square_fun.rst.md index 92105b3439b..84c2ac612c8 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Square_fun.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Square_fun.rst.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.Square -`qiskit.pulse.library.Square(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Square(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") A square wave pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.SymbolicPulse.md b/docs/api/qiskit/dev/qiskit.pulse.library.SymbolicPulse.md index 5b90afbdbaf..57c81c46338 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.SymbolicPulse.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.SymbolicPulse.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.library.SymbolicPulse -`qiskit.pulse.library.SymbolicPulse(pulse_type, duration, parameters=None, name=None, limit_amplitude=None, envelope=None, constraints=None, valid_amp_conditions=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.SymbolicPulse(pulse_type, duration, parameters=None, name=None, limit_amplitude=None, envelope=None, constraints=None, valid_amp_conditions=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") Bases: `Pulse` diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Triangle_class.rst.md b/docs/api/qiskit/dev/qiskit.pulse.library.Triangle_class.rst.md index d326c4313df..9a64a6e44cd 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Triangle_class.rst.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Triangle_class.rst.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.Triangle -`qiskit.pulse.library.Triangle(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.Triangle(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") A triangle wave pulse. diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.Waveform.md b/docs/api/qiskit/dev/qiskit.pulse.library.Waveform.md index 0e37751a7f9..8d23183a834 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.Waveform.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.Waveform.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.library.Waveform -`qiskit.pulse.library.Waveform(samples, name=None, epsilon=1e-07, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/waveform.py "view source code") +`qiskit.pulse.library.Waveform(samples, name=None, epsilon=1e-07, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/waveform.py "view source code") Bases: `Pulse` diff --git a/docs/api/qiskit/dev/qiskit.pulse.library.gaussian_square_echo.md b/docs/api/qiskit/dev/qiskit.pulse.library.gaussian_square_echo.md index 399127c1482..5910fc4ba3a 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.library.gaussian_square_echo.md +++ b/docs/api/qiskit/dev/qiskit.pulse.library.gaussian_square_echo.md @@ -12,7 +12,7 @@ python_api_name: qiskit.pulse.library.gaussian_square_echo -`qiskit.pulse.library.gaussian_square_echo(duration, amp, sigma, width=None, angle=0.0, active_amp=0.0, active_angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/library/symbolic_pulses.py "view source code") +`qiskit.pulse.library.gaussian_square_echo(duration, amp, sigma, width=None, angle=0.0, active_amp=0.0, active_angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/library/symbolic_pulses.py "view source code") An echoed Gaussian square pulse with an active tone overlaid on it. diff --git a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignEquispaced.md b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignEquispaced.md index 6d67cca6cc1..951e5365198 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignEquispaced.md +++ b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignEquispaced.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.transforms.AlignEquispaced -`qiskit.pulse.transforms.AlignEquispaced(duration)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/alignments.py "view source code") +`qiskit.pulse.transforms.AlignEquispaced(duration)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/alignments.py "view source code") Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") diff --git a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignFunc.md b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignFunc.md index abea2edf19b..fec0e9b96d0 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignFunc.md +++ b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignFunc.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.transforms.AlignFunc -`qiskit.pulse.transforms.AlignFunc(duration, func)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/alignments.py "view source code") +`qiskit.pulse.transforms.AlignFunc(duration, func)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/alignments.py "view source code") Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") diff --git a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignLeft.md b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignLeft.md index 9e231331aa8..c5fbe14ff1d 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignLeft.md +++ b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignLeft.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.transforms.AlignLeft -`qiskit.pulse.transforms.AlignLeft`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/alignments.py "view source code") +`qiskit.pulse.transforms.AlignLeft`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/alignments.py "view source code") Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") diff --git a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignRight.md b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignRight.md index 18f136b9f5c..4798cc1b720 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignRight.md +++ b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignRight.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.transforms.AlignRight -`qiskit.pulse.transforms.AlignRight`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/alignments.py "view source code") +`qiskit.pulse.transforms.AlignRight`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/alignments.py "view source code") Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") diff --git a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignSequential.md b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignSequential.md index 448b0d3a283..9a741e4389e 100644 --- a/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignSequential.md +++ b/docs/api/qiskit/dev/qiskit.pulse.transforms.AlignSequential.md @@ -10,7 +10,7 @@ python_api_name: qiskit.pulse.transforms.AlignSequential -`qiskit.pulse.transforms.AlignSequential`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/pulse/transforms/alignments.py "view source code") +`qiskit.pulse.transforms.AlignSequential`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/pulse/transforms/alignments.py "view source code") Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") diff --git a/docs/api/qiskit/dev/qiskit.qobj.GateCalibration.md b/docs/api/qiskit/dev/qiskit.qobj.GateCalibration.md index 6bd2bf91029..adcf6ad291a 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.GateCalibration.md +++ b/docs/api/qiskit/dev/qiskit.qobj.GateCalibration.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.GateCalibration -`qiskit.qobj.GateCalibration(name, qubits, params, instructions)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.GateCalibration(name, qubits, params, instructions)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.PulseLibraryItem.md b/docs/api/qiskit/dev/qiskit.qobj.PulseLibraryItem.md index 40677679d75..9d145495310 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.PulseLibraryItem.md +++ b/docs/api/qiskit/dev/qiskit.qobj.PulseLibraryItem.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.PulseLibraryItem -`qiskit.qobj.PulseLibraryItem(name, samples)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.PulseLibraryItem(name, samples)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.PulseQobj.md b/docs/api/qiskit/dev/qiskit.qobj.PulseQobj.md index f6412186a11..f4c9ef8d73d 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.PulseQobj.md +++ b/docs/api/qiskit/dev/qiskit.qobj.PulseQobj.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.PulseQobj -`qiskit.qobj.PulseQobj(qobj_id, config, experiments, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.PulseQobj(qobj_id, config, experiments, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjConfig.md b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjConfig.md index 1a37b901024..b9054098f54 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjConfig.md +++ b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.PulseQobjConfig -`qiskit.qobj.PulseQobjConfig(meas_level, meas_return, pulse_library, qubit_lo_freq, meas_lo_freq, memory_slot_size=None, rep_time=None, rep_delay=None, shots=None, seed_simulator=None, memory_slots=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.PulseQobjConfig(meas_level, meas_return, pulse_library, qubit_lo_freq, meas_lo_freq, memory_slot_size=None, rep_time=None, rep_delay=None, shots=None, seed_simulator=None, memory_slots=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: `QobjDictField` diff --git a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperiment.md b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperiment.md index 11a750521d2..9ff45c6f67c 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperiment.md +++ b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperiment.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.PulseQobjExperiment -`qiskit.qobj.PulseQobjExperiment(instructions, config=None, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.PulseQobjExperiment(instructions, config=None, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperimentConfig.md b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperimentConfig.md index 97939b0f442..3bbfd822f66 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperimentConfig.md +++ b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjExperimentConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.PulseQobjExperimentConfig -`qiskit.qobj.PulseQobjExperimentConfig(qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.PulseQobjExperimentConfig(qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: `QobjDictField` diff --git a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjInstruction.md b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjInstruction.md index 4b650e72fb5..32af7ed6f97 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.PulseQobjInstruction.md +++ b/docs/api/qiskit/dev/qiskit.qobj.PulseQobjInstruction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.PulseQobjInstruction -`qiskit.qobj.PulseQobjInstruction(name, t0, ch=None, conditional=None, val=None, phase=None, duration=None, qubits=None, memory_slot=None, register_slot=None, kernels=None, discriminators=None, label=None, type=None, pulse_shape=None, parameters=None, frequency=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.PulseQobjInstruction(name, t0, ch=None, conditional=None, val=None, phase=None, duration=None, qubits=None, memory_slot=None, register_slot=None, kernels=None, discriminators=None, label=None, type=None, pulse_shape=None, parameters=None, frequency=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QasmExperimentCalibrations.md b/docs/api/qiskit/dev/qiskit.qobj.QasmExperimentCalibrations.md index 68aae9f8739..40efb7f9d2f 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QasmExperimentCalibrations.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QasmExperimentCalibrations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QasmExperimentCalibrations -`qiskit.qobj.QasmExperimentCalibrations(gates)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.QasmExperimentCalibrations(gates)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QasmQobj.md b/docs/api/qiskit/dev/qiskit.qobj.QasmQobj.md index 1d93403219d..91c7e1c897a 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QasmQobj.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QasmQobj.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QasmQobj -`qiskit.qobj.QasmQobj(qobj_id=None, config=None, experiments=None, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.QasmQobj(qobj_id=None, config=None, experiments=None, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjConfig.md b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjConfig.md index 60b39f3eb86..c713b6a018b 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjConfig.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QasmQobjConfig -`qiskit.qobj.QasmQobjConfig(shots=None, seed_simulator=None, memory=None, parameter_binds=None, meas_level=None, meas_return=None, memory_slots=None, n_qubits=None, pulse_library=None, calibrations=None, rep_delay=None, qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.QasmQobjConfig(shots=None, seed_simulator=None, memory=None, parameter_binds=None, meas_level=None, meas_return=None, memory_slots=None, n_qubits=None, pulse_library=None, calibrations=None, rep_delay=None, qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: [`SimpleNamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperiment.md b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperiment.md index a48dd24a41a..750ae020bc9 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperiment.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperiment.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QasmQobjExperiment -`qiskit.qobj.QasmQobjExperiment(config=None, header=None, instructions=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.QasmQobjExperiment(config=None, header=None, instructions=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperimentConfig.md b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperimentConfig.md index 017b231b65e..53785139ca4 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperimentConfig.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjExperimentConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QasmQobjExperimentConfig -`qiskit.qobj.QasmQobjExperimentConfig(calibrations=None, qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.QasmQobjExperimentConfig(calibrations=None, qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: `QobjDictField` diff --git a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjInstruction.md b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjInstruction.md index 06010de146e..11cc5fc2004 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QasmQobjInstruction.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QasmQobjInstruction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QasmQobjInstruction -`qiskit.qobj.QasmQobjInstruction(name, params=None, qubits=None, register=None, memory=None, condition=None, conditional=None, label=None, mask=None, relation=None, val=None, snapshot_type=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/qasm_qobj.py "view source code") +`qiskit.qobj.QasmQobjInstruction(name, params=None, qubits=None, register=None, memory=None, condition=None, conditional=None, label=None, mask=None, relation=None, val=None, snapshot_type=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/qasm_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QobjExperimentHeader.md b/docs/api/qiskit/dev/qiskit.qobj.QobjExperimentHeader.md index bd888f57d88..c1f1a3e4ca5 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QobjExperimentHeader.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QobjExperimentHeader.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QobjExperimentHeader -`qiskit.qobj.QobjExperimentHeader(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/common.py "view source code") +`qiskit.qobj.QobjExperimentHeader(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/common.py "view source code") Bases: [`QobjHeader`](qiskit.qobj.QobjHeader "qiskit.qobj.common.QobjHeader") diff --git a/docs/api/qiskit/dev/qiskit.qobj.QobjHeader.md b/docs/api/qiskit/dev/qiskit.qobj.QobjHeader.md index 0601628af9b..66fdc25b902 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QobjHeader.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QobjHeader.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QobjHeader -`qiskit.qobj.QobjHeader(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/common.py "view source code") +`qiskit.qobj.QobjHeader(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/common.py "view source code") Bases: `QobjDictField` diff --git a/docs/api/qiskit/dev/qiskit.qobj.QobjMeasurementOption.md b/docs/api/qiskit/dev/qiskit.qobj.QobjMeasurementOption.md index d1303344237..e3dd1880d9b 100644 --- a/docs/api/qiskit/dev/qiskit.qobj.QobjMeasurementOption.md +++ b/docs/api/qiskit/dev/qiskit.qobj.QobjMeasurementOption.md @@ -10,7 +10,7 @@ python_api_name: qiskit.qobj.QobjMeasurementOption -`qiskit.qobj.QobjMeasurementOption(name, params=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qobj/pulse_qobj.py "view source code") +`qiskit.qobj.QobjMeasurementOption(name, params=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qobj/pulse_qobj.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.CNOTDihedral.md b/docs/api/qiskit/dev/qiskit.quantum_info.CNOTDihedral.md index 897d3290473..2879c580971 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.CNOTDihedral.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.CNOTDihedral.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.CNOTDihedral -`qiskit.quantum_info.CNOTDihedral(data=None, num_qubits=None, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/dihedral/dihedral.py "view source code") +`qiskit.quantum_info.CNOTDihedral(data=None, num_qubits=None, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/dihedral/dihedral.py "view source code") Bases: `BaseOperator`, `AdjointMixin` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Chi.md b/docs/api/qiskit/dev/qiskit.quantum_info.Chi.md index b5fe3270b72..5873e052ae0 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Chi.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Chi.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Chi -`qiskit.quantum_info.Chi(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/channel/chi.py "view source code") +`qiskit.quantum_info.Chi(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/channel/chi.py "view source code") Bases: `QuantumChannel` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Choi.md b/docs/api/qiskit/dev/qiskit.quantum_info.Choi.md index 58ec2639ce7..b451ee94e0d 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Choi.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Choi.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Choi -`qiskit.quantum_info.Choi(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/channel/choi.py "view source code") +`qiskit.quantum_info.Choi(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/channel/choi.py "view source code") Bases: `QuantumChannel` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Clifford.md b/docs/api/qiskit/dev/qiskit.quantum_info.Clifford.md index 0c2976d8d4a..59ae0f5fffe 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Clifford.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Clifford.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Clifford -`qiskit.quantum_info.Clifford(data, validate=True, copy=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/clifford.py "view source code") +`qiskit.quantum_info.Clifford(data, validate=True, copy=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/clifford.py "view source code") Bases: `BaseOperator`, `AdjointMixin`, [`Operation`](qiskit.circuit.Operation "qiskit.circuit.operation.Operation") diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.DensityMatrix.md b/docs/api/qiskit/dev/qiskit.quantum_info.DensityMatrix.md index b32be37b786..ccd6b3f2cd9 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.DensityMatrix.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.DensityMatrix.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.DensityMatrix -`qiskit.quantum_info.DensityMatrix(data, dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/densitymatrix.py "view source code") +`qiskit.quantum_info.DensityMatrix(data, dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/densitymatrix.py "view source code") Bases: `QuantumState`, `TolerancesMixin` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Kraus.md b/docs/api/qiskit/dev/qiskit.quantum_info.Kraus.md index 5bc240fb806..b8a7e8fd032 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Kraus.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Kraus.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Kraus -`qiskit.quantum_info.Kraus(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/channel/kraus.py "view source code") +`qiskit.quantum_info.Kraus(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/channel/kraus.py "view source code") Bases: `QuantumChannel` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Operator.md b/docs/api/qiskit/dev/qiskit.quantum_info.Operator.md index 681ebbd6a4b..367e5bb9ff3 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Operator.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Operator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Operator -`qiskit.quantum_info.Operator(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/operator.py "view source code") +`qiskit.quantum_info.Operator(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/operator.py "view source code") Bases: `LinearOp` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.PTM.md b/docs/api/qiskit/dev/qiskit.quantum_info.PTM.md index b0c29567b5a..36282e7dd8f 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.PTM.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.PTM.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.PTM -`qiskit.quantum_info.PTM(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/channel/ptm.py "view source code") +`qiskit.quantum_info.PTM(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/channel/ptm.py "view source code") Bases: `QuantumChannel` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.md b/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.md index 8b8c30e030e..69b666d2ace 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Pauli.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Pauli -`qiskit.quantum_info.Pauli(data=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/pauli.py "view source code") +`qiskit.quantum_info.Pauli(data=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/pauli.py "view source code") Bases: `BasePauli` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.PauliList.md b/docs/api/qiskit/dev/qiskit.quantum_info.PauliList.md index 58de6047ff0..10b9d6ee988 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.PauliList.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.PauliList.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.PauliList -`qiskit.quantum_info.PauliList(data)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/pauli_list.py "view source code") +`qiskit.quantum_info.PauliList(data)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/pauli_list.py "view source code") Bases: `BasePauli`, `LinearMixin`, `GroupMixin` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Quaternion.md b/docs/api/qiskit/dev/qiskit.quantum_info.Quaternion.md index e27f29e1b87..594cf260e76 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Quaternion.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Quaternion.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Quaternion -`qiskit.quantum_info.Quaternion(data)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/quaternion.py "view source code") +`qiskit.quantum_info.Quaternion(data)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/quaternion.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.ScalarOp.md b/docs/api/qiskit/dev/qiskit.quantum_info.ScalarOp.md index 13dccc4c96c..71fecf8e848 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.ScalarOp.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.ScalarOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.ScalarOp -`qiskit.quantum_info.ScalarOp(dims=None, coeff=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/scalar_op.py "view source code") +`qiskit.quantum_info.ScalarOp(dims=None, coeff=1)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/scalar_op.py "view source code") Bases: `LinearOp` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.SparsePauliOp.md b/docs/api/qiskit/dev/qiskit.quantum_info.SparsePauliOp.md index 1a9a8acf050..e70010484dd 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.SparsePauliOp.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.SparsePauliOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.SparsePauliOp -`qiskit.quantum_info.SparsePauliOp(data, coeffs=None, *, ignore_pauli_phase=False, copy=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/sparse_pauli_op.py "view source code") +`qiskit.quantum_info.SparsePauliOp(data, coeffs=None, *, ignore_pauli_phase=False, copy=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/sparse_pauli_op.py "view source code") Bases: `LinearOp` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.StabilizerState.md b/docs/api/qiskit/dev/qiskit.quantum_info.StabilizerState.md index 3dadbf9a7ab..a303087cd6e 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.StabilizerState.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.StabilizerState.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.StabilizerState -`qiskit.quantum_info.StabilizerState(data, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/stabilizerstate.py "view source code") +`qiskit.quantum_info.StabilizerState(data, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/stabilizerstate.py "view source code") Bases: `QuantumState` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Statevector.md b/docs/api/qiskit/dev/qiskit.quantum_info.Statevector.md index f0e07d44d64..aa2635c9ca8 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Statevector.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Statevector.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Statevector -`qiskit.quantum_info.Statevector(data, dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/statevector.py "view source code") +`qiskit.quantum_info.Statevector(data, dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/statevector.py "view source code") Bases: `QuantumState`, `TolerancesMixin` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Stinespring.md b/docs/api/qiskit/dev/qiskit.quantum_info.Stinespring.md index 670a301f83f..ea888f2be1b 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Stinespring.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Stinespring.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Stinespring -`qiskit.quantum_info.Stinespring(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/channel/stinespring.py "view source code") +`qiskit.quantum_info.Stinespring(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/channel/stinespring.py "view source code") Bases: `QuantumChannel` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.SuperOp.md b/docs/api/qiskit/dev/qiskit.quantum_info.SuperOp.md index 41f3534c5a0..f029ea9dadc 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.SuperOp.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.SuperOp.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.SuperOp -`qiskit.quantum_info.SuperOp(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/channel/superop.py "view source code") +`qiskit.quantum_info.SuperOp(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/channel/superop.py "view source code") Bases: `QuantumChannel` diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.Z2Symmetries.md b/docs/api/qiskit/dev/qiskit.quantum_info.Z2Symmetries.md index 13f0797ad41..83dc9a5e679 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.Z2Symmetries.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.Z2Symmetries.md @@ -10,7 +10,7 @@ python_api_name: qiskit.quantum_info.Z2Symmetries -`qiskit.quantum_info.Z2Symmetries(symmetries, sq_paulis, sq_list, tapering_values=None, *, tol=1e-14)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/analysis/z2_symmetries.py "view source code") +`qiskit.quantum_info.Z2Symmetries(symmetries, sq_paulis, sq_list, tapering_values=None, *, tol=1e-14)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/analysis/z2_symmetries.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") @@ -160,7 +160,7 @@ The second step of the reduction consists in replacing these qubits with the pos **Parameters** -**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – The to-be-tapered operator. +**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")) – The to-be-tapered operator. **Returns** @@ -180,7 +180,7 @@ Operate the second part of the tapering. This function assumes that the input op **Parameters** -**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – Partially tapered operator resulting from a call to [`convert_clifford()`](#qiskit.quantum_info.Z2Symmetries.convert_clifford "qiskit.quantum_info.Z2Symmetries.convert_clifford"). +**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")) – Partially tapered operator resulting from a call to [`convert_clifford()`](#qiskit.quantum_info.Z2Symmetries.convert_clifford "qiskit.quantum_info.Z2Symmetries.convert_clifford"). **Returns** diff --git a/docs/api/qiskit/dev/qiskit.quantum_info.pauli_basis.md b/docs/api/qiskit/dev/qiskit.quantum_info.pauli_basis.md index 170305757a1..e1415994f71 100644 --- a/docs/api/qiskit/dev/qiskit.quantum_info.pauli_basis.md +++ b/docs/api/qiskit/dev/qiskit.quantum_info.pauli_basis.md @@ -12,7 +12,7 @@ python_api_name: qiskit.quantum_info.pauli_basis -`qiskit.quantum_info.pauli_basis(num_qubits, weight=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/pauli_utils.py "view source code") +`qiskit.quantum_info.pauli_basis(num_qubits, weight=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/pauli_utils.py "view source code") Return the ordered PauliList for the n-qubit Pauli basis. diff --git a/docs/api/qiskit/dev/qiskit.result.BaseReadoutMitigator.md b/docs/api/qiskit/dev/qiskit.result.BaseReadoutMitigator.md index 18ac294222d..9b13d5d5491 100644 --- a/docs/api/qiskit/dev/qiskit.result.BaseReadoutMitigator.md +++ b/docs/api/qiskit/dev/qiskit.result.BaseReadoutMitigator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.BaseReadoutMitigator -`qiskit.result.BaseReadoutMitigator`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/mitigation/base_readout_mitigator.py "view source code") +`qiskit.result.BaseReadoutMitigator`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/mitigation/base_readout_mitigator.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.result.CorrelatedReadoutMitigator.md b/docs/api/qiskit/dev/qiskit.result.CorrelatedReadoutMitigator.md index 4497ab09e87..11296131744 100644 --- a/docs/api/qiskit/dev/qiskit.result.CorrelatedReadoutMitigator.md +++ b/docs/api/qiskit/dev/qiskit.result.CorrelatedReadoutMitigator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.CorrelatedReadoutMitigator -`qiskit.result.CorrelatedReadoutMitigator(assignment_matrix, qubits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/mitigation/correlated_readout_mitigator.py "view source code") +`qiskit.result.CorrelatedReadoutMitigator(assignment_matrix, qubits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/mitigation/correlated_readout_mitigator.py "view source code") Bases: [`BaseReadoutMitigator`](qiskit.result.BaseReadoutMitigator "qiskit.result.mitigation.base_readout_mitigator.BaseReadoutMitigator") diff --git a/docs/api/qiskit/dev/qiskit.result.Counts.md b/docs/api/qiskit/dev/qiskit.result.Counts.md index 8305598304c..6594920a8f4 100644 --- a/docs/api/qiskit/dev/qiskit.result.Counts.md +++ b/docs/api/qiskit/dev/qiskit.result.Counts.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.Counts -`qiskit.result.Counts(data, time_taken=None, creg_sizes=None, memory_slots=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/counts.py "view source code") +`qiskit.result.Counts(data, time_taken=None, creg_sizes=None, memory_slots=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/counts.py "view source code") Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") @@ -158,7 +158,7 @@ The bit string for the most frequent result `pop(k[, d]) → v, remove specified key and return the corresponding value.` -If key is not found, d is returned if given, otherwise KeyError is raised +If key is not found, default is returned if given, otherwise KeyError is raised ### popitem diff --git a/docs/api/qiskit/dev/qiskit.result.LocalReadoutMitigator.md b/docs/api/qiskit/dev/qiskit.result.LocalReadoutMitigator.md index e44aa66bf36..cf81965bbe1 100644 --- a/docs/api/qiskit/dev/qiskit.result.LocalReadoutMitigator.md +++ b/docs/api/qiskit/dev/qiskit.result.LocalReadoutMitigator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.LocalReadoutMitigator -`qiskit.result.LocalReadoutMitigator(assignment_matrices=None, qubits=None, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/mitigation/local_readout_mitigator.py "view source code") +`qiskit.result.LocalReadoutMitigator(assignment_matrices=None, qubits=None, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/mitigation/local_readout_mitigator.py "view source code") Bases: [`BaseReadoutMitigator`](qiskit.result.BaseReadoutMitigator "qiskit.result.mitigation.base_readout_mitigator.BaseReadoutMitigator") diff --git a/docs/api/qiskit/dev/qiskit.result.ProbDistribution.md b/docs/api/qiskit/dev/qiskit.result.ProbDistribution.md index 30a68da52e1..62ec0dd847c 100644 --- a/docs/api/qiskit/dev/qiskit.result.ProbDistribution.md +++ b/docs/api/qiskit/dev/qiskit.result.ProbDistribution.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.ProbDistribution -`qiskit.result.ProbDistribution(data, shots=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/distributions/probability.py "view source code") +`qiskit.result.ProbDistribution(data, shots=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/distributions/probability.py "view source code") Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") @@ -123,7 +123,7 @@ format `"0x1a"` `pop(k[, d]) → v, remove specified key and return the corresponding value.` -If key is not found, d is returned if given, otherwise KeyError is raised +If key is not found, default is returned if given, otherwise KeyError is raised ### popitem diff --git a/docs/api/qiskit/dev/qiskit.result.QuasiDistribution.md b/docs/api/qiskit/dev/qiskit.result.QuasiDistribution.md index eb2a4da06c4..25eb4693fca 100644 --- a/docs/api/qiskit/dev/qiskit.result.QuasiDistribution.md +++ b/docs/api/qiskit/dev/qiskit.result.QuasiDistribution.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.QuasiDistribution -`qiskit.result.QuasiDistribution(data, shots=None, stddev_upper_bound=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/distributions/quasi.py "view source code") +`qiskit.result.QuasiDistribution(data, shots=None, stddev_upper_bound=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/distributions/quasi.py "view source code") Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") @@ -161,7 +161,7 @@ Method from Smolin et al., Phys. Rev. Lett. 108, 070502 (2012). `pop(k[, d]) → v, remove specified key and return the corresponding value.` -If key is not found, d is returned if given, otherwise KeyError is raised +If key is not found, default is returned if given, otherwise KeyError is raised ### popitem diff --git a/docs/api/qiskit/dev/qiskit.result.Result.md b/docs/api/qiskit/dev/qiskit.result.Result.md index 6ca1397d0ea..7eff1354388 100644 --- a/docs/api/qiskit/dev/qiskit.result.Result.md +++ b/docs/api/qiskit/dev/qiskit.result.Result.md @@ -10,7 +10,7 @@ python_api_name: qiskit.result.Result -`qiskit.result.Result(backend_name, backend_version, qobj_id, job_id, success, results, date=None, status=None, header=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/result.py "view source code") +`qiskit.result.Result(backend_name, backend_version, qobj_id, job_id, success, results, date=None, status=None, header=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/result.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.result.ResultError.md b/docs/api/qiskit/dev/qiskit.result.ResultError.md index f099eab0d8b..c0a5895f7ae 100644 --- a/docs/api/qiskit/dev/qiskit.result.ResultError.md +++ b/docs/api/qiskit/dev/qiskit.result.ResultError.md @@ -12,7 +12,7 @@ python_api_name: qiskit.result.ResultError -`qiskit.result.ResultError(error)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/exceptions.py "view source code") +`qiskit.result.ResultError(error)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/exceptions.py "view source code") Exceptions raised due to errors in result output. diff --git a/docs/api/qiskit/dev/qiskit.synthesis.EvolutionSynthesis.md b/docs/api/qiskit/dev/qiskit.synthesis.EvolutionSynthesis.md index e559e8732a0..5bdfaf92294 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.EvolutionSynthesis.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.EvolutionSynthesis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.EvolutionSynthesis -`qiskit.synthesis.EvolutionSynthesis`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/evolution/evolution_synthesis.py "view source code") +`qiskit.synthesis.EvolutionSynthesis`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/evolution/evolution_synthesis.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.LieTrotter.md b/docs/api/qiskit/dev/qiskit.synthesis.LieTrotter.md index b8d618d58b0..38a70102e52 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.LieTrotter.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.LieTrotter.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.LieTrotter -`qiskit.synthesis.LieTrotter(reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/evolution/lie_trotter.py "view source code") +`qiskit.synthesis.LieTrotter(reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/evolution/lie_trotter.py "view source code") Bases: [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.evolution.product_formula.ProductFormula") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.MatrixExponential.md b/docs/api/qiskit/dev/qiskit.synthesis.MatrixExponential.md index 85ddd158e92..efcfa0d5bf4 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.MatrixExponential.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.MatrixExponential.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.MatrixExponential -`qiskit.synthesis.MatrixExponential`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/evolution/matrix_synthesis.py "view source code") +`qiskit.synthesis.MatrixExponential`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/evolution/matrix_synthesis.py "view source code") Bases: [`EvolutionSynthesis`](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.evolution.evolution_synthesis.EvolutionSynthesis") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.OneQubitEulerDecomposer.md b/docs/api/qiskit/dev/qiskit.synthesis.OneQubitEulerDecomposer.md index 944d85c3fd7..2b4ff60b518 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.OneQubitEulerDecomposer.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.OneQubitEulerDecomposer.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.OneQubitEulerDecomposer -`qiskit.synthesis.OneQubitEulerDecomposer(basis='U3', use_dag=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/one_qubit/one_qubit_decompose.py "view source code") +`qiskit.synthesis.OneQubitEulerDecomposer(basis='U3', use_dag=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/one_qubit/one_qubit_decompose.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.ProductFormula.md b/docs/api/qiskit/dev/qiskit.synthesis.ProductFormula.md index 52042e67fee..7c1c78b8ae8 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.ProductFormula.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.ProductFormula.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.ProductFormula -`qiskit.synthesis.ProductFormula(order, reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/evolution/product_formula.py "view source code") +`qiskit.synthesis.ProductFormula(order, reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/evolution/product_formula.py "view source code") Bases: [`EvolutionSynthesis`](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.evolution.evolution_synthesis.EvolutionSynthesis") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.QDrift.md b/docs/api/qiskit/dev/qiskit.synthesis.QDrift.md index d1482229c7a..025b7222434 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.QDrift.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.QDrift.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.QDrift -`qiskit.synthesis.QDrift(reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/evolution/qdrift.py "view source code") +`qiskit.synthesis.QDrift(reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/evolution/qdrift.py "view source code") Bases: [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.evolution.product_formula.ProductFormula") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.SolovayKitaevDecomposition.md b/docs/api/qiskit/dev/qiskit.synthesis.SolovayKitaevDecomposition.md index 83dce1b921e..bc546ee1272 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.SolovayKitaevDecomposition.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.SolovayKitaevDecomposition.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.SolovayKitaevDecomposition -`qiskit.synthesis.SolovayKitaevDecomposition(basic_approximations=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/discrete_basis/solovay_kitaev.py "view source code") +`qiskit.synthesis.SolovayKitaevDecomposition(basic_approximations=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/discrete_basis/solovay_kitaev.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.SuzukiTrotter.md b/docs/api/qiskit/dev/qiskit.synthesis.SuzukiTrotter.md index 0555bc2e65a..fc83e15bb25 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.SuzukiTrotter.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.SuzukiTrotter.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.SuzukiTrotter -`qiskit.synthesis.SuzukiTrotter(order=2, reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/evolution/suzuki_trotter.py "view source code") +`qiskit.synthesis.SuzukiTrotter(order=2, reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/evolution/suzuki_trotter.py "view source code") Bases: [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.evolution.product_formula.ProductFormula") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitBasisDecomposer.md b/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitBasisDecomposer.md index 6524a09935e..c2e4ac1f638 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitBasisDecomposer.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitBasisDecomposer.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.TwoQubitBasisDecomposer -`qiskit.synthesis.TwoQubitBasisDecomposer(gate, basis_fidelity=1.0, euler_basis='U', pulse_optimize=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/two_qubit/two_qubit_decompose.py "view source code") +`qiskit.synthesis.TwoQubitBasisDecomposer(gate, basis_fidelity=1.0, euler_basis='U', pulse_optimize=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/two_qubit/two_qubit_decompose.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitWeylDecomposition.md b/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitWeylDecomposition.md index c0d46153055..cb967ded672 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitWeylDecomposition.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.TwoQubitWeylDecomposition.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.TwoQubitWeylDecomposition -`qiskit.synthesis.TwoQubitWeylDecomposition(unitary_matrix, *, fidelity=0.999999999, _unpickling=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/two_qubit/two_qubit_decompose.py "view source code") +`qiskit.synthesis.TwoQubitWeylDecomposition(unitary_matrix, *, fidelity=0.999999999, _unpickling=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/two_qubit/two_qubit_decompose.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") @@ -151,7 +151,7 @@ Decode bytes into [`TwoQubitWeylDecomposition`](#qiskit.synthesis.TwoQubitWeylDe **Return type** -[TwoQubitWeylDecomposition](#qiskit.synthesis.TwoQubitWeylDecomposition "qiskit.synthesis.TwoQubitWeylDecomposition") +[*TwoQubitWeylDecomposition*](#qiskit.synthesis.TwoQubitWeylDecomposition "qiskit.synthesis.two_qubit.two_qubit_decompose.TwoQubitWeylDecomposition") ### specialize diff --git a/docs/api/qiskit/dev/qiskit.synthesis.XXDecomposer.md b/docs/api/qiskit/dev/qiskit.synthesis.XXDecomposer.md index 6301c045e47..30640855ea1 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.XXDecomposer.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.XXDecomposer.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.XXDecomposer -`qiskit.synthesis.XXDecomposer(basis_fidelity=1.0, euler_basis='U', embodiments=None, backup_optimizer=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/two_qubit/xx_decompose/decomposer.py "view source code") +`qiskit.synthesis.XXDecomposer(basis_fidelity=1.0, euler_basis='U', embodiments=None, backup_optimizer=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/two_qubit/xx_decompose/decomposer.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.AQC.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.AQC.md index 70139a03627..03bdeaa67fa 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.AQC.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.AQC.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.AQC -`qiskit.synthesis.unitary.aqc.AQC(optimizer=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/aqc.py "view source code") +`qiskit.synthesis.unitary.aqc.AQC(optimizer=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/aqc.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md index 785b2629ca4..23636a5e610 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.ApproximateCircuit -`qiskit.synthesis.unitary.aqc.ApproximateCircuit(num_qubits, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/approximate.py "view source code") +`qiskit.synthesis.unitary.aqc.ApproximateCircuit(num_qubits, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/approximate.py "view source code") Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md index dd8e8c1b434..bb7a1ce3091 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.ApproximatingObjective -`qiskit.synthesis.unitary.aqc.ApproximatingObjective`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/approximate.py "view source code") +`qiskit.synthesis.unitary.aqc.ApproximatingObjective`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/approximate.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md index 6832aa22951..6a2abc6287d 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.CNOTUnitCircuit -`qiskit.synthesis.unitary.aqc.CNOTUnitCircuit(num_qubits, cnots, tol=0.0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/cnot_unit_circuit.py "view source code") +`qiskit.synthesis.unitary.aqc.CNOTUnitCircuit(num_qubits, cnots, tol=0.0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/cnot_unit_circuit.py "view source code") Bases: [`ApproximateCircuit`](qiskit.synthesis.unitary.aqc.ApproximateCircuit "qiskit.synthesis.unitary.aqc.approximate.ApproximateCircuit") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md index b335662b4cd..41109a34076 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.CNOTUnitObjective -`qiskit.synthesis.unitary.aqc.CNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/cnot_unit_objective.py "view source code") +`qiskit.synthesis.unitary.aqc.CNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/cnot_unit_objective.py "view source code") Bases: [`ApproximatingObjective`](qiskit.synthesis.unitary.aqc.ApproximatingObjective "qiskit.synthesis.unitary.aqc.approximate.ApproximatingObjective"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md index fdd54051215..168b0d36749 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective -`qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/cnot_unit_objective.py "view source code") +`qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/cnot_unit_objective.py "view source code") Bases: [`CNOTUnitObjective`](qiskit.synthesis.unitary.aqc.CNOTUnitObjective "qiskit.synthesis.unitary.aqc.cnot_unit_objective.CNOTUnitObjective") diff --git a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md index 54127746fb0..23e78a14686 100644 --- a/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md +++ b/docs/api/qiskit/dev/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md @@ -10,7 +10,7 @@ python_api_name: qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective -`qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/fast_gradient/fast_gradient.py "view source code") +`qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/fast_gradient/fast_gradient.py "view source code") Bases: [`CNOTUnitObjective`](qiskit.synthesis.unitary.aqc.CNOTUnitObjective "qiskit.synthesis.unitary.aqc.cnot_unit_objective.CNOTUnitObjective") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.AnalysisPass.md b/docs/api/qiskit/dev/qiskit.transpiler.AnalysisPass.md index b1510776152..e7d97758ce0 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.AnalysisPass.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.AnalysisPass.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.AnalysisPass -`qiskit.transpiler.AnalysisPass(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/basepasses.py "view source code") +`qiskit.transpiler.AnalysisPass(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/basepasses.py "view source code") Bases: `BasePass` @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.CouplingMap.md b/docs/api/qiskit/dev/qiskit.transpiler.CouplingMap.md index 0012b4c057b..df7c2603470 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.CouplingMap.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.CouplingMap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.CouplingMap -`qiskit.transpiler.CouplingMap(couplinglist=None, description=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/coupling.py "view source code") +`qiskit.transpiler.CouplingMap(couplinglist=None, description=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/coupling.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.InstructionDurations.md b/docs/api/qiskit/dev/qiskit.transpiler.InstructionDurations.md index 4178494f8cd..64d1e283a9c 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.InstructionDurations.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.InstructionDurations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.InstructionDurations -`qiskit.transpiler.InstructionDurations(instruction_durations=None, dt=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/instruction_durations.py "view source code") +`qiskit.transpiler.InstructionDurations(instruction_durations=None, dt=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/instruction_durations.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.InstructionProperties.md b/docs/api/qiskit/dev/qiskit.transpiler.InstructionProperties.md index ea2e7bc5d3c..c2f5180f177 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.InstructionProperties.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.InstructionProperties.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.InstructionProperties -`qiskit.transpiler.InstructionProperties(duration=None, error=None, calibration=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/target.py "view source code") +`qiskit.transpiler.InstructionProperties(duration=None, error=None, calibration=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/target.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.Layout.md b/docs/api/qiskit/dev/qiskit.transpiler.Layout.md index 3449347c7fc..35578f8a5b6 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.Layout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.Layout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.Layout -`qiskit.transpiler.Layout(input_dict=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/layout.py "view source code") +`qiskit.transpiler.Layout(input_dict=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/layout.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.PassManager.md b/docs/api/qiskit/dev/qiskit.transpiler.PassManager.md index 852aceb6040..c0239022534 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.PassManager.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.PassManager.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.PassManager -`qiskit.transpiler.PassManager(passes=(), max_iteration=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passmanager.py "view source code") +`qiskit.transpiler.PassManager(passes=(), max_iteration=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passmanager.py "view source code") Bases: [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.passmanager.BasePassManager") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.PassManagerConfig.md b/docs/api/qiskit/dev/qiskit.transpiler.PassManagerConfig.md index d53af0a3474..cb6759a2946 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.PassManagerConfig.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.PassManagerConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.PassManagerConfig -`qiskit.transpiler.PassManagerConfig(initial_layout=None, basis_gates=None, inst_map=None, coupling_map=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, backend_properties=None, approximation_degree=None, seed_transpiler=None, timing_constraints=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passmanager_config.py "view source code") +`qiskit.transpiler.PassManagerConfig(initial_layout=None, basis_gates=None, inst_map=None, coupling_map=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, backend_properties=None, approximation_degree=None, seed_transpiler=None, timing_constraints=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passmanager_config.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.StagedPassManager.md b/docs/api/qiskit/dev/qiskit.transpiler.StagedPassManager.md index 819b0df60eb..ed6da56792d 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.StagedPassManager.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.StagedPassManager.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.StagedPassManager -`qiskit.transpiler.StagedPassManager(stages=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passmanager.py "view source code") +`qiskit.transpiler.StagedPassManager(stages=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passmanager.py "view source code") Bases: [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.passmanager.PassManager") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.Target.md b/docs/api/qiskit/dev/qiskit.transpiler.Target.md index b3690479892..c0d28eb81b6 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.Target.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.Target.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.Target -`qiskit.transpiler.Target(description=None, num_qubits=0, dt=None, granularity=1, min_length=1, pulse_alignment=1, acquire_alignment=1, qubit_properties=None, concurrent_measurements=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/target.py "view source code") +`qiskit.transpiler.Target(description=None, num_qubits=0, dt=None, granularity=1, min_length=1, pulse_alignment=1, acquire_alignment=1, qubit_properties=None, concurrent_measurements=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/target.py "view source code") Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.TransformationPass.md b/docs/api/qiskit/dev/qiskit.transpiler.TransformationPass.md index 38e9a7f3e34..6d6ad890aae 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.TransformationPass.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.TransformationPass.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.TransformationPass -`qiskit.transpiler.TransformationPass(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/basepasses.py "view source code") +`qiskit.transpiler.TransformationPass(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/basepasses.py "view source code") Bases: `BasePass` @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.TranspileLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.TranspileLayout.md index d4a7cd3ff54..f8b10eb78ec 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.TranspileLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.TranspileLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.TranspileLayout -`qiskit.transpiler.TranspileLayout(initial_layout, input_qubit_mapping, final_layout=None, _input_qubit_count=None, _output_qubit_list=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/layout.py "view source code") +`qiskit.transpiler.TranspileLayout(initial_layout, input_qubit_mapping, final_layout=None, _input_qubit_count=None, _output_qubit_list=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/layout.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPSchedule.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPSchedule.md index e08e66c4ad2..9f27817f34f 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPSchedule.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPSchedule.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ALAPSchedule -`qiskit.transpiler.passes.ALAPSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/alap.py "view source code") +`qiskit.transpiler.passes.ALAPSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/alap.py "view source code") Bases: `BaseSchedulerTransform` @@ -58,9 +58,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -68,7 +68,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPScheduleAnalysis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPScheduleAnalysis.md index d2a4030bea6..f4556683cff 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPScheduleAnalysis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ALAPScheduleAnalysis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ALAPScheduleAnalysis -`qiskit.transpiler.passes.ALAPScheduleAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/scheduling/alap.py "view source code") +`qiskit.transpiler.passes.ALAPScheduleAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/scheduling/alap.py "view source code") Bases: `BaseScheduler` @@ -61,9 +61,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -71,7 +71,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.AQCSynthesisPlugin.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.AQCSynthesisPlugin.md index dbbc472afcb..9c3b753a78a 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.AQCSynthesisPlugin.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.AQCSynthesisPlugin.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.AQCSynthesisPlugin -`qiskit.transpiler.passes.AQCSynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/aqc_plugin.py "view source code") +`qiskit.transpiler.passes.AQCSynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/aqc_plugin.py "view source code") Bases: [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPSchedule.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPSchedule.md index b6d060213ee..bd8349267fb 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPSchedule.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPSchedule.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ASAPSchedule -`qiskit.transpiler.passes.ASAPSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/asap.py "view source code") +`qiskit.transpiler.passes.ASAPSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/asap.py "view source code") Bases: `BaseSchedulerTransform` @@ -62,9 +62,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -72,7 +72,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPScheduleAnalysis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPScheduleAnalysis.md index 8a0f8f596aa..8036595fd00 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPScheduleAnalysis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ASAPScheduleAnalysis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ASAPScheduleAnalysis -`qiskit.transpiler.passes.ASAPScheduleAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/scheduling/asap.py "view source code") +`qiskit.transpiler.passes.ASAPScheduleAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/scheduling/asap.py "view source code") Bases: `BaseScheduler` @@ -61,9 +61,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -71,7 +71,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.AlignMeasures.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.AlignMeasures.md index bbb1b963973..83a0e2919eb 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.AlignMeasures.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.AlignMeasures.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.AlignMeasures -`qiskit.transpiler.passes.AlignMeasures(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/alignments/align_measures.py "view source code") +`qiskit.transpiler.passes.AlignMeasures(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/alignments/align_measures.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -94,9 +94,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -104,7 +104,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ApplyLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ApplyLayout.md index 37d147136d4..94c8c4927e0 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ApplyLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ApplyLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ApplyLayout -`qiskit.transpiler.passes.ApplyLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/apply_layout.py "view source code") +`qiskit.transpiler.passes.ApplyLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/apply_layout.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -50,9 +50,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -60,7 +60,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md index 439d97b8d97..80631c6e038 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.BarrierBeforeFinalMeasurements -`qiskit.transpiler.passes.BarrierBeforeFinalMeasurements(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/barrier_before_final_measurements.py "view source code") +`qiskit.transpiler.passes.BarrierBeforeFinalMeasurements(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/barrier_before_final_measurements.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.BasicSwap.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.BasicSwap.md index efe5ea224c7..a850c9fc604 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.BasicSwap.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.BasicSwap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.BasicSwap -`qiskit.transpiler.passes.BasicSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/routing/basic_swap.py "view source code") +`qiskit.transpiler.passes.BasicSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/routing/basic_swap.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -55,9 +55,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -65,7 +65,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.BasisTranslator.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.BasisTranslator.md index 657e87ed495..dc70d02e358 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.BasisTranslator.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.BasisTranslator.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.BasisTranslator -`qiskit.transpiler.passes.BasisTranslator(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/basis/basis_translator.py "view source code") +`qiskit.transpiler.passes.BasisTranslator(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/basis/basis_translator.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -101,9 +101,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -111,7 +111,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CSPLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CSPLayout.md index 1ae663ec7f9..dd298a98642 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CSPLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CSPLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CSPLayout -`qiskit.transpiler.passes.CSPLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/csp_layout.py "view source code") +`qiskit.transpiler.passes.CSPLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/csp_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -63,9 +63,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -73,7 +73,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CXCancellation.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CXCancellation.md index 522c09b5ea4..b375a4ba74b 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CXCancellation.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CXCancellation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CXCancellation -`qiskit.transpiler.passes.CXCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/cx_cancellation.py "view source code") +`qiskit.transpiler.passes.CXCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/cx_cancellation.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckGateDirection.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckGateDirection.md index bbd7379373c..b8b129d8bd0 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckGateDirection.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckGateDirection.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CheckGateDirection -`qiskit.transpiler.passes.CheckGateDirection(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/check_gate_direction.py "view source code") +`qiskit.transpiler.passes.CheckGateDirection(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/check_gate_direction.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -53,9 +53,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -63,7 +63,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckMap.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckMap.md index 61fdacce800..d277e1f9f88 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckMap.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CheckMap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CheckMap -`qiskit.transpiler.passes.CheckMap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/check_map.py "view source code") +`qiskit.transpiler.passes.CheckMap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/check_map.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -55,9 +55,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -65,7 +65,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect1qRuns.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect1qRuns.md index 4840f061afc..6d559844d36 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect1qRuns.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect1qRuns.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Collect1qRuns -`qiskit.transpiler.passes.Collect1qRuns(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/collect_1q_runs.py "view source code") +`qiskit.transpiler.passes.Collect1qRuns(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/collect_1q_runs.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect2qBlocks.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect2qBlocks.md index 924329c86fe..1af63525e31 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect2qBlocks.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Collect2qBlocks.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Collect2qBlocks -`qiskit.transpiler.passes.Collect2qBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/collect_2q_blocks.py "view source code") +`qiskit.transpiler.passes.Collect2qBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/collect_2q_blocks.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectCliffords.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectCliffords.md index 617360f7223..2a99c6fb004 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectCliffords.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectCliffords.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CollectCliffords -`qiskit.transpiler.passes.CollectCliffords(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/collect_cliffords.py "view source code") +`qiskit.transpiler.passes.CollectCliffords(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/collect_cliffords.py "view source code") Bases: `CollectAndCollapse` @@ -56,9 +56,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -66,7 +66,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectLinearFunctions.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectLinearFunctions.md index 44b40c6388d..b71e6f95360 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectLinearFunctions.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectLinearFunctions.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CollectLinearFunctions -`qiskit.transpiler.passes.CollectLinearFunctions(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/collect_linear_functions.py "view source code") +`qiskit.transpiler.passes.CollectLinearFunctions(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/collect_linear_functions.py "view source code") Bases: `CollectAndCollapse` @@ -56,9 +56,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -66,7 +66,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectMultiQBlocks.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectMultiQBlocks.md index e18b2ea6f51..39870e8353e 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectMultiQBlocks.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CollectMultiQBlocks.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CollectMultiQBlocks -`qiskit.transpiler.passes.CollectMultiQBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/collect_multiqubit_blocks.py "view source code") +`qiskit.transpiler.passes.CollectMultiQBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/collect_multiqubit_blocks.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -56,9 +56,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -66,7 +66,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### find\_set diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutationAnalysis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutationAnalysis.md index 6b316e7f078..63e6fc36abd 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutationAnalysis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutationAnalysis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CommutationAnalysis -`qiskit.transpiler.passes.CommutationAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/commutation_analysis.py "view source code") +`qiskit.transpiler.passes.CommutationAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/commutation_analysis.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeCancellation.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeCancellation.md index 6034a58fc27..9bb013f3756 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeCancellation.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeCancellation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CommutativeCancellation -`qiskit.transpiler.passes.CommutativeCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/commutative_cancellation.py "view source code") +`qiskit.transpiler.passes.CommutativeCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/commutative_cancellation.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -59,9 +59,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -69,7 +69,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeInverseCancellation.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeInverseCancellation.md index 2bf137a8b9f..282c8136d59 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeInverseCancellation.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CommutativeInverseCancellation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CommutativeInverseCancellation -`qiskit.transpiler.passes.CommutativeInverseCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/commutative_inverse_cancellation.py "view source code") +`qiskit.transpiler.passes.CommutativeInverseCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/commutative_inverse_cancellation.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -51,9 +51,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -61,7 +61,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.md index 3610af2423e..c9ac7b41ba1 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Commuting2qGateRouter.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Commuting2qGateRouter -`qiskit.transpiler.passes.Commuting2qGateRouter(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/routing/commuting_2q_gate_routing/commuting_2q_gate_router.py "view source code") +`qiskit.transpiler.passes.Commuting2qGateRouter(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/routing/commuting_2q_gate_routing/commuting_2q_gate_router.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -108,9 +108,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -118,7 +118,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.md index 586ea5d2aae..95534b80353 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ConsolidateBlocks -`qiskit.transpiler.passes.ConsolidateBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/consolidate_blocks.py "view source code") +`qiskit.transpiler.passes.ConsolidateBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/consolidate_blocks.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -64,9 +64,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -74,7 +74,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConstrainedReschedule.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConstrainedReschedule.md index ad4dde427c7..340ac43d60e 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConstrainedReschedule.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConstrainedReschedule.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ConstrainedReschedule -`qiskit.transpiler.passes.ConstrainedReschedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/alignments/reschedule.py "view source code") +`qiskit.transpiler.passes.ConstrainedReschedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/alignments/reschedule.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -83,9 +83,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -93,7 +93,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ContainsInstruction.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ContainsInstruction.md index 7ad2a5c754e..a82b430e853 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ContainsInstruction.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ContainsInstruction.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ContainsInstruction -`qiskit.transpiler.passes.ContainsInstruction(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/contains_instruction.py "view source code") +`qiskit.transpiler.passes.ContainsInstruction(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/contains_instruction.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -55,9 +55,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -65,7 +65,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConvertConditionsToIfOps.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConvertConditionsToIfOps.md index 10307630c1e..0014defc8fb 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConvertConditionsToIfOps.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConvertConditionsToIfOps.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ConvertConditionsToIfOps -`qiskit.transpiler.passes.ConvertConditionsToIfOps(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/convert_conditions_to_if_ops.py "view source code") +`qiskit.transpiler.passes.ConvertConditionsToIfOps(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/convert_conditions_to_if_ops.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOps.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOps.md index 4a21f4779ac..4f4606cace6 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOps.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOps.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CountOps -`qiskit.transpiler.passes.CountOps(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/count_ops.py "view source code") +`qiskit.transpiler.passes.CountOps(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/count_ops.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOpsLongestPath.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOpsLongestPath.md index 80381013978..95d4ff8033c 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOpsLongestPath.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.CountOpsLongestPath.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.CountOpsLongestPath -`qiskit.transpiler.passes.CountOpsLongestPath(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/count_ops_longest_path.py "view source code") +`qiskit.transpiler.passes.CountOpsLongestPath(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/count_ops_longest_path.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGFixedPoint.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGFixedPoint.md index bb1bfcf4b73..911a8b9e5ae 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGFixedPoint.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGFixedPoint.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.DAGFixedPoint -`qiskit.transpiler.passes.DAGFixedPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/dag_fixed_point.py "view source code") +`qiskit.transpiler.passes.DAGFixedPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/dag_fixed_point.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGLongestPath.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGLongestPath.md index 3c0e5edc30d..ab0df88c034 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGLongestPath.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.DAGLongestPath.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.DAGLongestPath -`qiskit.transpiler.passes.DAGLongestPath(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/dag_longest_path.py "view source code") +`qiskit.transpiler.passes.DAGLongestPath(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/dag_longest_path.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Decompose.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Decompose.md index b4c382bc5bb..bdeac877b71 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Decompose.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Decompose.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Decompose -`qiskit.transpiler.passes.Decompose(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/basis/decompose.py "view source code") +`qiskit.transpiler.passes.Decompose(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/basis/decompose.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -52,9 +52,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -62,7 +62,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.DenseLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.DenseLayout.md index b97d191ff43..698cebf00a6 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.DenseLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.DenseLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.DenseLayout -`qiskit.transpiler.passes.DenseLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/dense_layout.py "view source code") +`qiskit.transpiler.passes.DenseLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/dense_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -60,9 +60,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -70,7 +70,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Depth.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Depth.md index ed21c74a069..13a1f7d6c69 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Depth.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Depth.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Depth -`qiskit.transpiler.passes.Depth(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/depth.py "view source code") +`qiskit.transpiler.passes.Depth(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/depth.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -50,9 +50,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -60,7 +60,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.DynamicalDecoupling.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.DynamicalDecoupling.md index 7ebfffa5265..bd259dfbe0b 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.DynamicalDecoupling.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.DynamicalDecoupling.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.DynamicalDecoupling -`qiskit.transpiler.passes.DynamicalDecoupling(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/dynamical_decoupling.py "view source code") +`qiskit.transpiler.passes.DynamicalDecoupling(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/dynamical_decoupling.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -129,9 +129,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -139,7 +139,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md index 6633e721590..67ff7249065 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.EchoRZXWeylDecomposition -`qiskit.transpiler.passes.EchoRZXWeylDecomposition(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/echo_rzx_weyl_decomposition.py "view source code") +`qiskit.transpiler.passes.EchoRZXWeylDecomposition(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/echo_rzx_weyl_decomposition.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -55,9 +55,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -65,7 +65,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.EnlargeWithAncilla.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.EnlargeWithAncilla.md index 37ea2c8135a..d967540ee8f 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.EnlargeWithAncilla.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.EnlargeWithAncilla.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.EnlargeWithAncilla -`qiskit.transpiler.passes.EnlargeWithAncilla(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/enlarge_with_ancilla.py "view source code") +`qiskit.transpiler.passes.EnlargeWithAncilla(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/enlarge_with_ancilla.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.FilterOpNodes.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.FilterOpNodes.md index bb3e9088c68..db73096e926 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.FilterOpNodes.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.FilterOpNodes.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.FilterOpNodes -`qiskit.transpiler.passes.FilterOpNodes(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/filter_op_nodes.py "view source code") +`qiskit.transpiler.passes.FilterOpNodes(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/filter_op_nodes.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -73,9 +73,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -83,7 +83,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.FixedPoint.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.FixedPoint.md index 8450741c5d2..c016f8fb4a9 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.FixedPoint.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.FixedPoint.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.FixedPoint -`qiskit.transpiler.passes.FixedPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/fixed_point.py "view source code") +`qiskit.transpiler.passes.FixedPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/fixed_point.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -54,9 +54,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -64,7 +64,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.FullAncillaAllocation.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.FullAncillaAllocation.md index 7c28a5956ad..5d833ff927c 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.FullAncillaAllocation.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.FullAncillaAllocation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.FullAncillaAllocation -`qiskit.transpiler.passes.FullAncillaAllocation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/full_ancilla_allocation.py "view source code") +`qiskit.transpiler.passes.FullAncillaAllocation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/full_ancilla_allocation.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -58,9 +58,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -68,7 +68,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.GateDirection.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.GateDirection.md index 60cd78b3a89..09fde6f97a8 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.GateDirection.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.GateDirection.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.GateDirection -`qiskit.transpiler.passes.GateDirection(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/gate_direction.py "view source code") +`qiskit.transpiler.passes.GateDirection(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/gate_direction.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -80,9 +80,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -90,7 +90,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.GatesInBasis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.GatesInBasis.md index 33135bb80c2..5dbc2178728 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.GatesInBasis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.GatesInBasis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.GatesInBasis -`qiskit.transpiler.passes.GatesInBasis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/gates_basis.py "view source code") +`qiskit.transpiler.passes.GatesInBasis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/gates_basis.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -53,9 +53,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -63,7 +63,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.HLSConfig.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.HLSConfig.md index 42e9112bc30..5ba64938749 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.HLSConfig.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.HLSConfig.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.HLSConfig -`qiskit.transpiler.passes.HLSConfig(use_default_on_unspecified=True, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/high_level_synthesis.py "view source code") +`qiskit.transpiler.passes.HLSConfig(use_default_on_unspecified=True, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/high_level_synthesis.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.HighLevelSynthesis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.HighLevelSynthesis.md index 377a903cffd..3c61166b2a2 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.HighLevelSynthesis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.HighLevelSynthesis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.HighLevelSynthesis -`qiskit.transpiler.passes.HighLevelSynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/high_level_synthesis.py "view source code") +`qiskit.transpiler.passes.HighLevelSynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/high_level_synthesis.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -80,9 +80,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -90,7 +90,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.HoareOptimizer.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.HoareOptimizer.md index 1dfdad6937f..d08164c7f41 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.HoareOptimizer.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.HoareOptimizer.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.HoareOptimizer -`qiskit.transpiler.passes.HoareOptimizer(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/hoare_opt.py "view source code") +`qiskit.transpiler.passes.HoareOptimizer(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/hoare_opt.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -54,9 +54,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -64,7 +64,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.InstructionDurationCheck.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.InstructionDurationCheck.md index 082113bf1dc..59ca37c8f34 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.InstructionDurationCheck.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.InstructionDurationCheck.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.InstructionDurationCheck -`qiskit.transpiler.passes.InstructionDurationCheck(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/alignments/check_durations.py "view source code") +`qiskit.transpiler.passes.InstructionDurationCheck(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/alignments/check_durations.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -59,9 +59,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -69,7 +69,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.InverseCancellation.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.InverseCancellation.md index 60362b9111e..db3a2142738 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.InverseCancellation.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.InverseCancellation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.InverseCancellation -`qiskit.transpiler.passes.InverseCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/inverse_cancellation.py "view source code") +`qiskit.transpiler.passes.InverseCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/inverse_cancellation.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -56,9 +56,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -66,7 +66,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Layout2qDistance.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Layout2qDistance.md index dc00985d58e..97dd335931f 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Layout2qDistance.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Layout2qDistance.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Layout2qDistance -`qiskit.transpiler.passes.Layout2qDistance(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/layout_2q_distance.py "view source code") +`qiskit.transpiler.passes.Layout2qDistance(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/layout_2q_distance.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -55,9 +55,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -65,7 +65,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.LinearFunctionsToPermutations.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.LinearFunctionsToPermutations.md index 9600bfe9443..5ffa0e58095 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.LinearFunctionsToPermutations.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.LinearFunctionsToPermutations.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.LinearFunctionsToPermutations -`qiskit.transpiler.passes.LinearFunctionsToPermutations(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/linear_functions_synthesis.py "view source code") +`qiskit.transpiler.passes.LinearFunctionsToPermutations(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/linear_functions_synthesis.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.LookaheadSwap.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.LookaheadSwap.md index 86684259778..6a1f2ee471b 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.LookaheadSwap.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.LookaheadSwap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.LookaheadSwap -`qiskit.transpiler.passes.LookaheadSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/routing/lookahead_swap.py "view source code") +`qiskit.transpiler.passes.LookaheadSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/routing/lookahead_swap.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -71,9 +71,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -81,7 +81,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.MergeAdjacentBarriers.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.MergeAdjacentBarriers.md index b427e3b68ad..7256e211cd8 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.MergeAdjacentBarriers.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.MergeAdjacentBarriers.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.MergeAdjacentBarriers -`qiskit.transpiler.passes.MergeAdjacentBarriers(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/merge_adjacent_barriers.py "view source code") +`qiskit.transpiler.passes.MergeAdjacentBarriers(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/merge_adjacent_barriers.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -83,9 +83,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -93,7 +93,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.MinimumPoint.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.MinimumPoint.md index 854cbad4945..ea4e553496a 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.MinimumPoint.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.MinimumPoint.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.MinimumPoint -`qiskit.transpiler.passes.MinimumPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/minimum_point.py "view source code") +`qiskit.transpiler.passes.MinimumPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/minimum_point.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -66,9 +66,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -76,7 +76,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.NormalizeRXAngle.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.NormalizeRXAngle.md index 32c064dbde8..f700e691bc0 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.NormalizeRXAngle.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.NormalizeRXAngle.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.NormalizeRXAngle -`qiskit.transpiler.passes.NormalizeRXAngle(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/normalize_rx_angle.py "view source code") +`qiskit.transpiler.passes.NormalizeRXAngle(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/normalize_rx_angle.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -68,9 +68,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -78,7 +78,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.NumTensorFactors.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.NumTensorFactors.md index 5af7faf3e2f..2280188a8c4 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.NumTensorFactors.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.NumTensorFactors.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.NumTensorFactors -`qiskit.transpiler.passes.NumTensorFactors(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/num_tensor_factors.py "view source code") +`qiskit.transpiler.passes.NumTensorFactors(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/num_tensor_factors.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGates.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGates.md index 6fd3559922a..e8526033cfd 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGates.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGates.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Optimize1qGates -`qiskit.transpiler.passes.Optimize1qGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/optimize_1q_gates.py "view source code") +`qiskit.transpiler.passes.Optimize1qGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/optimize_1q_gates.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -68,9 +68,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -78,7 +78,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md index d4878e03e81..8a777f31651 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Optimize1qGatesDecomposition -`qiskit.transpiler.passes.Optimize1qGatesDecomposition(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/optimize_1q_decomposition.py "view source code") +`qiskit.transpiler.passes.Optimize1qGatesDecomposition(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/optimize_1q_decomposition.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -62,9 +62,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -72,7 +72,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md index f0af77fbd44..05e4ade1201 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation -`qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/optimize_1q_commutation.py "view source code") +`qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/optimize_1q_commutation.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -58,9 +58,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -68,7 +68,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeAnnotated.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeAnnotated.md index 067901f9333..ef88a590f0f 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeAnnotated.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeAnnotated.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.OptimizeAnnotated -`qiskit.transpiler.passes.OptimizeAnnotated(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/optimize_annotated.py "view source code") +`qiskit.transpiler.passes.OptimizeAnnotated(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/optimize_annotated.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -61,9 +61,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -71,7 +71,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffords.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffords.md index dec86df34db..f6f34ece643 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffords.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffords.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.OptimizeCliffords -`qiskit.transpiler.passes.OptimizeCliffords(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/optimize_cliffords.py "view source code") +`qiskit.transpiler.passes.OptimizeCliffords(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/optimize_cliffords.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDelay.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDelay.md index 1c7140671fe..e70b5d25d4b 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDelay.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDelay.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.PadDelay -`qiskit.transpiler.passes.PadDelay(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/padding/pad_delay.py "view source code") +`qiskit.transpiler.passes.PadDelay(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/padding/pad_delay.py "view source code") Bases: `BasePadding` @@ -78,9 +78,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -88,7 +88,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDynamicalDecoupling.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDynamicalDecoupling.md index 3bbce93e5c8..f8de24e71a7 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDynamicalDecoupling.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.PadDynamicalDecoupling.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.PadDynamicalDecoupling -`qiskit.transpiler.passes.PadDynamicalDecoupling(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/padding/dynamical_decoupling.py "view source code") +`qiskit.transpiler.passes.PadDynamicalDecoupling(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/padding/dynamical_decoupling.py "view source code") Bases: `BasePadding` @@ -136,9 +136,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -146,7 +146,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.PulseGates.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.PulseGates.md index 531fc3d42fd..af79804df7f 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.PulseGates.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.PulseGates.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.PulseGates -`qiskit.transpiler.passes.PulseGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/calibration/pulse_gate.py "view source code") +`qiskit.transpiler.passes.PulseGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/calibration/pulse_gate.py "view source code") Bases: `CalibrationBuilder` @@ -65,9 +65,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -75,7 +75,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### get\_calibration diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RXCalibrationBuilder.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RXCalibrationBuilder.md index 1017e988b8a..4ac79f69c02 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RXCalibrationBuilder.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RXCalibrationBuilder.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RXCalibrationBuilder -`qiskit.transpiler.passes.RXCalibrationBuilder(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/calibration/rx_builder.py "view source code") +`qiskit.transpiler.passes.RXCalibrationBuilder(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/calibration/rx_builder.py "view source code") Bases: `CalibrationBuilder` @@ -96,9 +96,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -106,7 +106,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### get\_calibration diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilder.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilder.md index 9b627ac661c..fa0856b470a 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilder.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilder.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RZXCalibrationBuilder -`qiskit.transpiler.passes.RZXCalibrationBuilder(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/calibration/rzx_builder.py "view source code") +`qiskit.transpiler.passes.RZXCalibrationBuilder(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/calibration/rzx_builder.py "view source code") Bases: `CalibrationBuilder` @@ -58,9 +58,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -68,7 +68,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### get\_calibration diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md index b9d27b0dce3..075ab6de1ef 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho -`qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/calibration/rzx_builder.py "view source code") +`qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/calibration/rzx_builder.py "view source code") Bases: [`RZXCalibrationBuilder`](qiskit.transpiler.passes.RZXCalibrationBuilder "qiskit.transpiler.passes.calibration.rzx_builder.RZXCalibrationBuilder") @@ -60,9 +60,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -70,7 +70,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### get\_calibration diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveBarriers.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveBarriers.md index 1218f487218..2b793ae25ac 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveBarriers.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveBarriers.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RemoveBarriers -`qiskit.transpiler.passes.RemoveBarriers(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/remove_barriers.py "view source code") +`qiskit.transpiler.passes.RemoveBarriers(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/remove_barriers.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -65,9 +65,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -75,7 +75,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md index 57fa6a38edc..86657828c0a 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure -`qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/remove_diagonal_gates_before_measure.py "view source code") +`qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/remove_diagonal_gates_before_measure.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveFinalMeasurements.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveFinalMeasurements.md index 34bd2a51364..50fbacf72c8 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveFinalMeasurements.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveFinalMeasurements.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RemoveFinalMeasurements -`qiskit.transpiler.passes.RemoveFinalMeasurements(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/remove_final_measurements.py "view source code") +`qiskit.transpiler.passes.RemoveFinalMeasurements(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/remove_final_measurements.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -50,9 +50,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -60,7 +60,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveResetInZeroState.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveResetInZeroState.md index 0bd23239bb3..d3c9bfa924f 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveResetInZeroState.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.RemoveResetInZeroState.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.RemoveResetInZeroState -`qiskit.transpiler.passes.RemoveResetInZeroState(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/remove_reset_in_zero_state.py "view source code") +`qiskit.transpiler.passes.RemoveResetInZeroState(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/remove_reset_in_zero_state.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -46,9 +46,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -56,7 +56,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md index 956181bfd79..4451a235ebd 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ResetAfterMeasureSimplification -`qiskit.transpiler.passes.ResetAfterMeasureSimplification(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/reset_after_measure_simplification.py "view source code") +`qiskit.transpiler.passes.ResetAfterMeasureSimplification(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/reset_after_measure_simplification.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreLayout.md index 5a6b54b1fb3..3eaac81e306 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SabreLayout -`qiskit.transpiler.passes.SabreLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/sabre_layout.py "view source code") +`qiskit.transpiler.passes.SabreLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/sabre_layout.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -140,9 +140,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -150,7 +150,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SabrePreLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SabrePreLayout.md index 4461d04eea5..8ee541f55dd 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SabrePreLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SabrePreLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SabrePreLayout -`qiskit.transpiler.passes.SabrePreLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/sabre_pre_layout.py "view source code") +`qiskit.transpiler.passes.SabrePreLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/sabre_pre_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -110,9 +110,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -120,7 +120,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreSwap.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreSwap.md index 8586cc04fe2..9bd0f00d046 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreSwap.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SabreSwap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SabreSwap -`qiskit.transpiler.passes.SabreSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/routing/sabre_swap.py "view source code") +`qiskit.transpiler.passes.SabreSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/routing/sabre_swap.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -106,9 +106,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -116,7 +116,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SetIOLatency.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SetIOLatency.md index 55f37857aa9..9dccfd324f1 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SetIOLatency.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SetIOLatency.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SetIOLatency -`qiskit.transpiler.passes.SetIOLatency(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/scheduling/set_io_latency.py "view source code") +`qiskit.transpiler.passes.SetIOLatency(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/scheduling/set_io_latency.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -57,9 +57,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -67,7 +67,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SetLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SetLayout.md index 9890c34cd17..cb0e3522425 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SetLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SetLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SetLayout -`qiskit.transpiler.passes.SetLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/set_layout.py "view source code") +`qiskit.transpiler.passes.SetLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/set_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -59,9 +59,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -69,7 +69,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Size.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Size.md index 5a73d9d60dc..6184d4651ef 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Size.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Size.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Size -`qiskit.transpiler.passes.Size(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/size.py "view source code") +`qiskit.transpiler.passes.Size(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/size.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -52,9 +52,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -62,7 +62,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaev.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaev.md index ce07dd8ab87..c9e4d0e0199 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaev.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaev.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SolovayKitaev -`qiskit.transpiler.passes.SolovayKitaev(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py "view source code") +`qiskit.transpiler.passes.SolovayKitaev(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -135,9 +135,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -145,7 +145,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaevSynthesis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaevSynthesis.md index b38e892a665..7c3bbbb5366 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaevSynthesis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.SolovayKitaevSynthesis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.SolovayKitaevSynthesis -`qiskit.transpiler.passes.SolovayKitaevSynthesis`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py "view source code") +`qiskit.transpiler.passes.SolovayKitaevSynthesis`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py "view source code") Bases: [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.StochasticSwap.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.StochasticSwap.md index 80f0a23b9dc..2265c10c5b9 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.StochasticSwap.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.StochasticSwap.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.StochasticSwap -`qiskit.transpiler.passes.StochasticSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/routing/stochastic_swap.py "view source code") +`qiskit.transpiler.passes.StochasticSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/routing/stochastic_swap.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -67,9 +67,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -77,7 +77,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.TemplateOptimization.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.TemplateOptimization.md index ba41acf80ec..1f63f43eecb 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.TemplateOptimization.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.TemplateOptimization.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.TemplateOptimization -`qiskit.transpiler.passes.TemplateOptimization(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/optimization/template_optimization.py "view source code") +`qiskit.transpiler.passes.TemplateOptimization(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/optimization/template_optimization.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -53,9 +53,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -63,7 +63,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.TimeUnitConversion.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.TimeUnitConversion.md index b51a69f6757..70bf9dd6f05 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.TimeUnitConversion.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.TimeUnitConversion.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.TimeUnitConversion -`qiskit.transpiler.passes.TimeUnitConversion(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/time_unit_conversion.py "view source code") +`qiskit.transpiler.passes.TimeUnitConversion(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/time_unit_conversion.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -61,9 +61,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -71,7 +71,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.TranslateParameterizedGates.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.TranslateParameterizedGates.md index ae2d525828c..72bff72dd15 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.TranslateParameterizedGates.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.TranslateParameterizedGates.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.TranslateParameterizedGates -`qiskit.transpiler.passes.TranslateParameterizedGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/basis/translate_parameterized.py "view source code") +`qiskit.transpiler.passes.TranslateParameterizedGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/basis/translate_parameterized.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -103,9 +103,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -113,7 +113,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.TrivialLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.TrivialLayout.md index 809b0b85dfa..89a308bd387 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.TrivialLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.TrivialLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.TrivialLayout -`qiskit.transpiler.passes.TrivialLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/trivial_layout.py "view source code") +`qiskit.transpiler.passes.TrivialLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/trivial_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -62,9 +62,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -72,7 +72,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.UnitarySynthesis.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.UnitarySynthesis.md index 74e5a004975..630c29b9633 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.UnitarySynthesis.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.UnitarySynthesis.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.UnitarySynthesis -`qiskit.transpiler.passes.UnitarySynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/unitary_synthesis.py "view source code") +`qiskit.transpiler.passes.UnitarySynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/unitary_synthesis.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -68,9 +68,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -78,7 +78,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Unroll3qOrMore.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Unroll3qOrMore.md index fbf0c9679ce..a0e2ff4d78e 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Unroll3qOrMore.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Unroll3qOrMore.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Unroll3qOrMore -`qiskit.transpiler.passes.Unroll3qOrMore(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/basis/unroll_3q_or_more.py "view source code") +`qiskit.transpiler.passes.Unroll3qOrMore(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/basis/unroll_3q_or_more.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -53,9 +53,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -63,7 +63,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollCustomDefinitions.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollCustomDefinitions.md index 3c30f206d83..9785dd7e699 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollCustomDefinitions.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollCustomDefinitions.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.UnrollCustomDefinitions -`qiskit.transpiler.passes.UnrollCustomDefinitions(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/basis/unroll_custom_definitions.py "view source code") +`qiskit.transpiler.passes.UnrollCustomDefinitions(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/basis/unroll_custom_definitions.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -64,9 +64,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -74,7 +74,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollForLoops.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollForLoops.md index fdc8e82f6e2..76900293cb3 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollForLoops.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.UnrollForLoops.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.UnrollForLoops -`qiskit.transpiler.passes.UnrollForLoops(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/utils/unroll_forloops.py "view source code") +`qiskit.transpiler.passes.UnrollForLoops(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/utils/unroll_forloops.py "view source code") Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") @@ -56,9 +56,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -66,7 +66,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2Layout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2Layout.md index b3be79c3459..6307de9cf32 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2Layout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2Layout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.VF2Layout -`qiskit.transpiler.passes.VF2Layout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/vf2_layout.py "view source code") +`qiskit.transpiler.passes.VF2Layout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/vf2_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -82,9 +82,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -92,7 +92,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2PostLayout.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2PostLayout.md index 7e2207e8d35..3e754898f1b 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2PostLayout.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.VF2PostLayout.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.VF2PostLayout -`qiskit.transpiler.passes.VF2PostLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/layout/vf2_post_layout.py "view source code") +`qiskit.transpiler.passes.VF2PostLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/layout/vf2_post_layout.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -85,9 +85,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -95,7 +95,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ValidatePulseGates.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.ValidatePulseGates.md index d7a33496b40..c0027e692d4 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ValidatePulseGates.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ValidatePulseGates.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.ValidatePulseGates -`qiskit.transpiler.passes.ValidatePulseGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/scheduling/alignments/pulse_gate_validation.py "view source code") +`qiskit.transpiler.passes.ValidatePulseGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/scheduling/alignments/pulse_gate_validation.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -61,9 +61,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -71,7 +71,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.Width.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.Width.md index ed6c321ef61..4084d80f821 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.Width.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.Width.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.Width -`qiskit.transpiler.passes.Width(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/analysis/width.py "view source code") +`qiskit.transpiler.passes.Width(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/analysis/width.py "view source code") Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") @@ -48,9 +48,9 @@ Execute optimization task for input Qiskit IR. **Parameters** -* **passmanager\_ir** (*PassManagerIR*) – Qiskit IR to optimize. -* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")) – State associated with workflow execution by the pass manager itself. -* **callback** (*Callable*) – A callback function which is caller per execution of optimization task. +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. **Returns** @@ -58,7 +58,7 @@ Optimized Qiskit IR and state of the workflow. **Return type** -[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[PassManagerIR, [PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")] +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] ### name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md index 122292ca9b7..17d473802e7 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlu -`qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/plugin.py "view source code") +`qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/plugin.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md index 5a60c9c491c..483fc7c3891 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlu -`qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/plugin.py "view source code") +`qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/plugin.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md index f06c98bb2b9..3c703f05aa5 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugi -`qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/plugin.py "view source code") +`qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/plugin.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md index 852a54d65a4..9dae1e023e0 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugi -`qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/plugin.py "view source code") +`qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/plugin.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names.md index cd03d449267..966c136048b 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names.md @@ -12,7 +12,7 @@ python_api_name: qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_ -`qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names(op_name)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/plugin.py "view source code") +`qiskit.transpiler.passes.synthesis.plugin.high_level_synthesis_plugin_names(op_name)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/plugin.py "view source code") Return a list of plugin names installed for a given high level object name diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md index 909926f78ee..fa5de650272 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md @@ -12,7 +12,7 @@ python_api_name: qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plu -`qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/synthesis/plugin.py "view source code") +`qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/synthesis/plugin.py "view source code") Return a list of installed unitary synthesis plugin names diff --git a/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md b/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md index ee3278ce559..d3f3329f872 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePl -`qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") +`qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md b/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md index 2af5bf17061..52fbf97c229 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md +++ b/docs/api/qiskit/dev/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md @@ -10,7 +10,7 @@ python_api_name: qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePl -`qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") +`qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") diff --git a/docs/api/qiskit/dev/qiskit.visualization.array_to_latex.md b/docs/api/qiskit/dev/qiskit.visualization.array_to_latex.md index 9570532810b..7ffb6caf977 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.array_to_latex.md +++ b/docs/api/qiskit/dev/qiskit.visualization.array_to_latex.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.array_to_latex -`qiskit.visualization.array_to_latex(array, precision=10, prefix='', source=False, max_size=8)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/array.py "view source code") +`qiskit.visualization.array_to_latex(array, precision=10, prefix='', source=False, max_size=8)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/array.py "view source code") Latex representation of a complex numpy array (with dimension 1 or 2) diff --git a/docs/api/qiskit/dev/qiskit.visualization.circuit_drawer.md b/docs/api/qiskit/dev/qiskit.visualization.circuit_drawer.md index 7871c11f293..cf64fb0393d 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.circuit_drawer.md +++ b/docs/api/qiskit/dev/qiskit.visualization.circuit_drawer.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.circuit_drawer -`qiskit.visualization.circuit_drawer(circuit, scale=None, filename=None, style=None, output=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=True, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/circuit/circuit_visualization.py "view source code") +`qiskit.visualization.circuit_drawer(circuit, scale=None, filename=None, style=None, output=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=True, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/circuit/circuit_visualization.py "view source code") Draw the quantum circuit. Use the output parameter to choose the drawing format: diff --git a/docs/api/qiskit/dev/qiskit.visualization.dag_drawer.md b/docs/api/qiskit/dev/qiskit.visualization.dag_drawer.md index 62835d9cf50..a3e5c0bf8d2 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.dag_drawer.md +++ b/docs/api/qiskit/dev/qiskit.visualization.dag_drawer.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.dag_drawer -`qiskit.visualization.dag_drawer(dag, scale=0.7, filename=None, style='color')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/dag_visualization.py "view source code") +`qiskit.visualization.dag_drawer(dag, scale=0.7, filename=None, style='color')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/dag_visualization.py "view source code") Plot the directed acyclic graph (dag) to represent operation dependencies in a quantum circuit. diff --git a/docs/api/qiskit/dev/qiskit.visualization.pass_manager_drawer.md b/docs/api/qiskit/dev/qiskit.visualization.pass_manager_drawer.md index 34253360ff2..048ec80726a 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.pass_manager_drawer.md +++ b/docs/api/qiskit/dev/qiskit.visualization.pass_manager_drawer.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.pass_manager_drawer -`qiskit.visualization.pass_manager_drawer(pass_manager, filename=None, style=None, raw=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/pass_manager_visualization.py "view source code") +`qiskit.visualization.pass_manager_drawer(pass_manager, filename=None, style=None, raw=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/pass_manager_visualization.py "view source code") Draws the pass manager. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_multivector.md b/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_multivector.md index a07ca85bf5e..c770fc92377 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_multivector.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_multivector.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_bloch_multivector -`qiskit.visualization.plot_bloch_multivector(state, title='', figsize=None, *, reverse_bits=False, filename=None, font_size=None, title_font_size=None, title_pad=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/state_visualization.py "view source code") +`qiskit.visualization.plot_bloch_multivector(state, title='', figsize=None, *, reverse_bits=False, filename=None, font_size=None, title_font_size=None, title_pad=1)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/state_visualization.py "view source code") Plot a Bloch sphere for each qubit. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_vector.md b/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_vector.md index 56444eca617..14cf75aad43 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_vector.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_bloch_vector.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_bloch_vector -`qiskit.visualization.plot_bloch_vector(bloch, title='', ax=None, figsize=None, coord_type='cartesian', font_size=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/state_visualization.py "view source code") +`qiskit.visualization.plot_bloch_vector(bloch, title='', ax=None, figsize=None, coord_type='cartesian', font_size=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/state_visualization.py "view source code") Plot the Bloch sphere. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.md b/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.md index c68bdccf603..ed63cd2048b 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_circuit_layout.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_circuit_layout -`qiskit.visualization.plot_circuit_layout(circuit, backend, view='virtual', qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/gate_map.py "view source code") +`qiskit.visualization.plot_circuit_layout(circuit, backend, view='virtual', qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/gate_map.py "view source code") Plot the layout of a circuit transpiled for a given target backend. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_coupling_map.md b/docs/api/qiskit/dev/qiskit.visualization.plot_coupling_map.md index ceed2a23289..82c7a17ad60 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_coupling_map.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_coupling_map.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_coupling_map -`qiskit.visualization.plot_coupling_map(num_qubits, qubit_coordinates, coupling_map, figsize=None, plot_directed=False, label_qubits=True, qubit_size=None, line_width=4, font_size=None, qubit_color=None, qubit_labels=None, line_color=None, font_color='white', ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/gate_map.py "view source code") +`qiskit.visualization.plot_coupling_map(num_qubits, qubit_coordinates, coupling_map, figsize=None, plot_directed=False, label_qubits=True, qubit_size=None, line_width=4, font_size=None, qubit_color=None, qubit_labels=None, line_color=None, font_color='white', ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/gate_map.py "view source code") Plots an arbitrary coupling map of qubits (embedded in a plane). diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_distribution.md b/docs/api/qiskit/dev/qiskit.visualization.plot_distribution.md index 1417d0d76ff..370b4c05e33 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_distribution.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_distribution.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_distribution -`qiskit.visualization.plot_distribution(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/counts_visualization.py "view source code") +`qiskit.visualization.plot_distribution(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/counts_visualization.py "view source code") Plot a distribution from input sampled data. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.md b/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.md index d75e02243a8..f8a29ae578d 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_error_map.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_error_map -`qiskit.visualization.plot_error_map(backend, figsize=(15, 12), show_title=True, qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/gate_map.py "view source code") +`qiskit.visualization.plot_error_map(backend, figsize=(15, 12), show_title=True, qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/gate_map.py "view source code") Plots the error map of a given backend. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_gate_map.md b/docs/api/qiskit/dev/qiskit.visualization.plot_gate_map.md index b5df9eb6364..1760cff2353 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_gate_map.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_gate_map.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_gate_map -`qiskit.visualization.plot_gate_map(backend, figsize=None, plot_directed=False, label_qubits=True, qubit_size=None, line_width=4, font_size=None, qubit_color=None, qubit_labels=None, line_color=None, font_color='white', ax=None, filename=None, qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/gate_map.py "view source code") +`qiskit.visualization.plot_gate_map(backend, figsize=None, plot_directed=False, label_qubits=True, qubit_size=None, line_width=4, font_size=None, qubit_color=None, qubit_labels=None, line_color=None, font_color='white', ax=None, filename=None, qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/gate_map.py "view source code") Plots the gate map of a device. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_histogram.md b/docs/api/qiskit/dev/qiskit.visualization.plot_histogram.md index c4fa49df781..602f4d4ab8a 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_histogram.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_histogram.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_histogram -`qiskit.visualization.plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/counts_visualization.py "view source code") +`qiskit.visualization.plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/counts_visualization.py "view source code") Plot a histogram of input counts data. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_state_city.md b/docs/api/qiskit/dev/qiskit.visualization.plot_state_city.md index 365c1babb51..7d121c007a4 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_state_city.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_state_city.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_state_city -`qiskit.visualization.plot_state_city(state, title='', figsize=None, color=None, alpha=1, ax_real=None, ax_imag=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/state_visualization.py "view source code") +`qiskit.visualization.plot_state_city(state, title='', figsize=None, color=None, alpha=1, ax_real=None, ax_imag=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/state_visualization.py "view source code") Plot the cityscape of quantum state. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_state_hinton.md b/docs/api/qiskit/dev/qiskit.visualization.plot_state_hinton.md index 204203b1621..e9063cb06fd 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_state_hinton.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_state_hinton.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_state_hinton -`qiskit.visualization.plot_state_hinton(state, title='', figsize=None, ax_real=None, ax_imag=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/state_visualization.py "view source code") +`qiskit.visualization.plot_state_hinton(state, title='', figsize=None, ax_real=None, ax_imag=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/state_visualization.py "view source code") Plot a hinton diagram for the density matrix of a quantum state. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_state_paulivec.md b/docs/api/qiskit/dev/qiskit.visualization.plot_state_paulivec.md index 478feabfcf7..a617ddeb85f 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_state_paulivec.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_state_paulivec.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_state_paulivec -`qiskit.visualization.plot_state_paulivec(state, title='', figsize=None, color=None, ax=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/state_visualization.py "view source code") +`qiskit.visualization.plot_state_paulivec(state, title='', figsize=None, color=None, ax=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/state_visualization.py "view source code") Plot the Pauli-vector representation of a quantum state as bar graph. diff --git a/docs/api/qiskit/dev/qiskit.visualization.plot_state_qsphere.md b/docs/api/qiskit/dev/qiskit.visualization.plot_state_qsphere.md index 01c9b2c2364..54ae1f85c67 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.plot_state_qsphere.md +++ b/docs/api/qiskit/dev/qiskit.visualization.plot_state_qsphere.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.plot_state_qsphere -`qiskit.visualization.plot_state_qsphere(state, figsize=None, ax=None, show_state_labels=True, show_state_phases=False, use_degrees=False, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/state_visualization.py "view source code") +`qiskit.visualization.plot_state_qsphere(state, figsize=None, ax=None, show_state_labels=True, show_state_phases=False, use_degrees=False, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/state_visualization.py "view source code") Plot the qsphere representation of a quantum state. Here, the size of the points is proportional to the probability of the corresponding term in the state and the color represents the phase. diff --git a/docs/api/qiskit/dev/qiskit.visualization.visualize_transition.md b/docs/api/qiskit/dev/qiskit.visualization.visualize_transition.md index c81862c7581..2abe24407e5 100644 --- a/docs/api/qiskit/dev/qiskit.visualization.visualize_transition.md +++ b/docs/api/qiskit/dev/qiskit.visualization.visualize_transition.md @@ -12,7 +12,7 @@ python_api_name: qiskit.visualization.visualize_transition -`qiskit.visualization.visualize_transition(circuit, trace=False, saveas=None, fpg=100, spg=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/transition_visualization.py "view source code") +`qiskit.visualization.visualize_transition(circuit, trace=False, saveas=None, fpg=100, spg=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/transition_visualization.py "view source code") Creates animation showing transitions between states of a single qubit by applying quantum gates. diff --git a/docs/api/qiskit/dev/qpy.md b/docs/api/qiskit/dev/qpy.md index 21c490d063a..976110a226c 100644 --- a/docs/api/qiskit/dev/qpy.md +++ b/docs/api/qiskit/dev/qpy.md @@ -59,7 +59,7 @@ and then loading that file will return a list with all the circuits -`qiskit.qpy.load(file_obj, metadata_deserializer=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qpy/interface.py "view source code") +`qiskit.qpy.load(file_obj, metadata_deserializer=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qpy/interface.py "view source code") Load a QPY binary file @@ -106,7 +106,7 @@ The list of Qiskit programs contained in the QPY data. A list is always returned -`qiskit.qpy.dump(programs, file_obj, metadata_serializer=None, use_symengine=True, version=11)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qpy/interface.py "view source code") +`qiskit.qpy.dump(programs, file_obj, metadata_serializer=None, use_symengine=True, version=11)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qpy/interface.py "view source code") Write QPY binary data to a file @@ -172,7 +172,7 @@ These functions will raise a custom subclass of [`QiskitError`](exceptions#qiski -`qiskit.qpy.QpyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qpy/exceptions.py "view source code") +`qiskit.qpy.QpyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qpy/exceptions.py "view source code") Errors raised by the qpy module. @@ -210,7 +210,7 @@ If a feature being loaded is deprecated in the corresponding qiskit release, QPY -`qiskit.qpy.QPYLoadingDeprecatedFeatureWarning`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/qpy/exceptions.py "view source code") +`qiskit.qpy.QPYLoadingDeprecatedFeatureWarning`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/qpy/exceptions.py "view source code") Visible deprecation warning for QPY loading functions without a stable point in the call stack. diff --git a/docs/api/qiskit/dev/quantum_info.md b/docs/api/qiskit/dev/quantum_info.md index 1dde924133c..a169080911b 100644 --- a/docs/api/qiskit/dev/quantum_info.md +++ b/docs/api/qiskit/dev/quantum_info.md @@ -60,7 +60,7 @@ python_api_name: qiskit.quantum_info -`qiskit.quantum_info.average_gate_fidelity(channel, target=None, require_cp=True, require_tp=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/measures.py "view source code") +`qiskit.quantum_info.average_gate_fidelity(channel, target=None, require_cp=True, require_tp=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/measures.py "view source code") Return the average gate fidelity of a noisy quantum channel. @@ -102,7 +102,7 @@ The average gate fidelity $F_{\text{ave}}$. -`qiskit.quantum_info.process_fidelity(channel, target=None, require_cp=True, require_tp=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/measures.py "view source code") +`qiskit.quantum_info.process_fidelity(channel, target=None, require_cp=True, require_tp=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/measures.py "view source code") Return the process fidelity of a noisy quantum channel. @@ -151,7 +151,7 @@ The process fidelity $F_{\text{pro}}$. -`qiskit.quantum_info.gate_error(channel, target=None, require_cp=True, require_tp=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/measures.py "view source code") +`qiskit.quantum_info.gate_error(channel, target=None, require_cp=True, require_tp=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/measures.py "view source code") Return the gate error of a noisy quantum channel. @@ -188,7 +188,7 @@ The average gate error $E$. -`qiskit.quantum_info.diamond_norm(choi, solver='SCS', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/measures.py "view source code") +`qiskit.quantum_info.diamond_norm(choi, solver='SCS', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/measures.py "view source code") Return the diamond norm of the input quantum channel object. @@ -228,7 +228,7 @@ J. Watrous. “Simpler semidefinite programs for completely bounded norms”, ar -`qiskit.quantum_info.state_fidelity(state1, state2, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/measures.py "view source code") +`qiskit.quantum_info.state_fidelity(state1, state2, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/measures.py "view source code") Return the state fidelity between two quantum states. @@ -264,7 +264,7 @@ The state fidelity $F(\rho_1, \rho_2)$. -`qiskit.quantum_info.purity(state, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/measures.py "view source code") +`qiskit.quantum_info.purity(state, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/measures.py "view source code") Calculate the purity of a quantum state. @@ -295,7 +295,7 @@ the purity $Tr[\rho^2]$. -`qiskit.quantum_info.concurrence(state)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/measures.py "view source code") +`qiskit.quantum_info.concurrence(state)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/measures.py "view source code") Calculate the concurrence of a quantum state. @@ -337,7 +337,7 @@ The concurrence. -`qiskit.quantum_info.entropy(state, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/measures.py "view source code") +`qiskit.quantum_info.entropy(state, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/measures.py "view source code") Calculate the von-Neumann entropy of a quantum state. @@ -368,7 +368,7 @@ The von-Neumann entropy S(rho). -`qiskit.quantum_info.entanglement_of_formation(state)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/measures.py "view source code") +`qiskit.quantum_info.entanglement_of_formation(state)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/measures.py "view source code") Calculate the entanglement of formation of quantum state. @@ -396,7 +396,7 @@ The entanglement of formation. -`qiskit.quantum_info.mutual_information(state, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/measures.py "view source code") +`qiskit.quantum_info.mutual_information(state, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/measures.py "view source code") Calculate the mutual information of a bipartite state. @@ -436,7 +436,7 @@ The mutual information $I(\rho_{AB})$. -`qiskit.quantum_info.partial_trace(state, qargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/utils.py "view source code") +`qiskit.quantum_info.partial_trace(state, qargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/utils.py "view source code") Return reduced density matrix by tracing out part of quantum state. @@ -463,7 +463,7 @@ The reduced density matrix. -`qiskit.quantum_info.schmidt_decomposition(state, qargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/utils.py "view source code") +`qiskit.quantum_info.schmidt_decomposition(state, qargs)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/utils.py "view source code") Return the Schmidt Decomposition of a pure quantum state. @@ -513,7 +513,7 @@ list of tuples `(s, u, v)`, where `s` (float) are the Schmidt coefficients $\lam -`qiskit.quantum_info.shannon_entropy(pvec, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/utils.py "view source code") +`qiskit.quantum_info.shannon_entropy(pvec, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/utils.py "view source code") Compute the Shannon entropy of a probability vector. @@ -542,7 +542,7 @@ The Shannon entropy H(pvec). -`qiskit.quantum_info.commutator(a, b)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/utils/commutator.py "view source code") +`qiskit.quantum_info.commutator(a, b)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/utils/commutator.py "view source code") Compute commutator of a and b. @@ -567,7 +567,7 @@ The commutator -`qiskit.quantum_info.anti_commutator(a, b)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/utils/anti_commutator.py "view source code") +`qiskit.quantum_info.anti_commutator(a, b)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/utils/anti_commutator.py "view source code") Compute anti-commutator of a and b. @@ -592,7 +592,7 @@ The anti-commutator -`qiskit.quantum_info.double_commutator(a, b, c, *, commutator=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/utils/double_commutator.py "view source code") +`qiskit.quantum_info.double_commutator(a, b, c, *, commutator=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/utils/double_commutator.py "view source code") Compute symmetric double commutator of a, b and c. @@ -641,7 +641,7 @@ Methods of Molecular Quantum Mechanics. 2nd Edition, Academic Press, 1992. ISBN -`qiskit.quantum_info.random_statevector(dims, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/random.py "view source code") +`qiskit.quantum_info.random_statevector(dims, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/random.py "view source code") Generator a random Statevector. @@ -668,7 +668,7 @@ K. Zyczkowski and H. Sommers (2001), “Induced measures in the space of mixed q -`qiskit.quantum_info.random_density_matrix(dims, rank=None, method='Hilbert-Schmidt', seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/states/random.py "view source code") +`qiskit.quantum_info.random_density_matrix(dims, rank=None, method='Hilbert-Schmidt', seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/states/random.py "view source code") Generator a random DensityMatrix. @@ -695,7 +695,7 @@ the random density matrix. -`qiskit.quantum_info.random_unitary(dims, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/random.py "view source code") +`qiskit.quantum_info.random_unitary(dims, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/random.py "view source code") Return a random unitary Operator. @@ -718,7 +718,7 @@ a unitary operator. -`qiskit.quantum_info.random_hermitian(dims, traceless=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/random.py "view source code") +`qiskit.quantum_info.random_hermitian(dims, traceless=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/random.py "view source code") Return a random hermitian Operator. @@ -742,7 +742,7 @@ a Hermitian operator. -`qiskit.quantum_info.random_pauli(num_qubits, group_phase=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/random.py "view source code") +`qiskit.quantum_info.random_pauli(num_qubits, group_phase=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/random.py "view source code") Return a random Pauli. @@ -764,7 +764,7 @@ a random Pauli -`qiskit.quantum_info.random_clifford(num_qubits, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/random.py "view source code") +`qiskit.quantum_info.random_clifford(num_qubits, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/random.py "view source code") Return a random Clifford operator. @@ -791,7 +791,7 @@ a random Clifford operator. -`qiskit.quantum_info.random_quantum_channel(input_dims=None, output_dims=None, rank=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/random.py "view source code") +`qiskit.quantum_info.random_quantum_channel(input_dims=None, output_dims=None, rank=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/random.py "view source code") Return a random CPTP quantum channel. @@ -820,7 +820,7 @@ a quantum channel operator. -`qiskit.quantum_info.random_cnotdihedral(num_qubits, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/dihedral/random.py "view source code") +`qiskit.quantum_info.random_cnotdihedral(num_qubits, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/dihedral/random.py "view source code") Return a random CNOTDihedral element. @@ -841,7 +841,7 @@ a random CNOTDihedral element. -`qiskit.quantum_info.random_pauli_list(num_qubits, size=1, seed=None, phase=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/operators/symplectic/random.py "view source code") +`qiskit.quantum_info.random_pauli_list(num_qubits, size=1, seed=None, phase=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/operators/symplectic/random.py "view source code") Return a random PauliList. @@ -866,7 +866,7 @@ a random PauliList. -`qiskit.quantum_info.hellinger_distance(dist_p, dist_q)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/analysis/distance.py "view source code") +`qiskit.quantum_info.hellinger_distance(dist_p, dist_q)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/analysis/distance.py "view source code") Computes the Hellinger distance between two counts distributions. @@ -891,7 +891,7 @@ Distance -`qiskit.quantum_info.hellinger_fidelity(dist_p, dist_q)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/quantum_info/analysis/distance.py "view source code") +`qiskit.quantum_info.hellinger_fidelity(dist_p, dist_q)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/quantum_info/analysis/distance.py "view source code") Computes the Hellinger fidelity between two counts distributions. diff --git a/docs/api/qiskit/dev/result.md b/docs/api/qiskit/dev/result.md index f7723e13ace..2a627522f62 100644 --- a/docs/api/qiskit/dev/result.md +++ b/docs/api/qiskit/dev/result.md @@ -28,7 +28,7 @@ python_api_name: qiskit.result -`qiskit.result.marginal_counts(result, indices=None, inplace=False, format_marginal=False, marginalize_memory=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/utils.py "view source code") +`qiskit.result.marginal_counts(result, indices=None, inplace=False, format_marginal=False, marginalize_memory=True)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/utils.py "view source code") Marginalize counts from an experiment over some indices of interest. @@ -58,7 +58,7 @@ the observed counts, marginalized to only account for frequency of observations -`qiskit.result.marginal_distribution(counts, indices=None, format_marginal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/utils.py "view source code") +`qiskit.result.marginal_distribution(counts, indices=None, format_marginal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/utils.py "view source code") Marginalize counts from an experiment over some indices of interest. @@ -87,7 +87,7 @@ A marginalized dictionary -`qiskit.result.marginal_memory(memory, indices=None, int_return=False, hex_return=False, avg_data=False, parallel_threshold=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/utils.py "view source code") +`qiskit.result.marginal_memory(memory, indices=None, int_return=False, hex_return=False, avg_data=False, parallel_threshold=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/utils.py "view source code") Marginalize shot memory @@ -127,7 +127,7 @@ marginal\_memory -`qiskit.result.sampled_expectation_value(dist, oper)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/result/sampled_expval.py "view source code") +`qiskit.result.sampled_expectation_value(dist, oper)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/result/sampled_expval.py "view source code") Computes expectation value from a sampled distribution diff --git a/docs/api/qiskit/dev/scheduler.md b/docs/api/qiskit/dev/scheduler.md index f3636be6be5..ee27bb2209f 100644 --- a/docs/api/qiskit/dev/scheduler.md +++ b/docs/api/qiskit/dev/scheduler.md @@ -22,7 +22,7 @@ A circuit scheduler compiles a circuit program to a pulse program. -`qiskit.scheduler.ScheduleConfig(inst_map, meas_map, dt)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/scheduler/config.py "view source code") +`qiskit.scheduler.ScheduleConfig(inst_map, meas_map, dt)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/scheduler/config.py "view source code") Configuration for pulse scheduling. @@ -38,7 +38,7 @@ Container for information needed to schedule a QuantumCircuit into a pulse Sched -`qiskit.scheduler.schedule_circuit.schedule_circuit(circuit, schedule_config, method=None, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/scheduler/schedule_circuit.py "view source code") +`qiskit.scheduler.schedule_circuit.schedule_circuit(circuit, schedule_config, method=None, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/scheduler/schedule_circuit.py "view source code") Basic scheduling pass from a circuit to a pulse Schedule, using the backend. If no method is specified, then a basic, as late as possible scheduling pass is performed, i.e. pulses are scheduled to occur as late as possible. @@ -74,7 +74,7 @@ Pulse scheduling methods. -`qiskit.scheduler.methods.as_soon_as_possible(circuit, schedule_config, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/scheduler/methods/basic.py "view source code") +`qiskit.scheduler.methods.as_soon_as_possible(circuit, schedule_config, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/scheduler/methods/basic.py "view source code") Return the pulse Schedule which implements the input circuit using an “as soon as possible” (asap) scheduling policy. @@ -98,7 +98,7 @@ A schedule corresponding to the input `circuit` with pulses occurring as early a -`qiskit.scheduler.methods.as_late_as_possible(circuit, schedule_config, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/scheduler/methods/basic.py "view source code") +`qiskit.scheduler.methods.as_late_as_possible(circuit, schedule_config, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/scheduler/methods/basic.py "view source code") Return the pulse Schedule which implements the input circuit using an “as late as possible” (alap) scheduling policy. diff --git a/docs/api/qiskit/dev/synthesis.md b/docs/api/qiskit/dev/synthesis.md index 29cc21d9fd5..2ce7e550397 100644 --- a/docs/api/qiskit/dev/synthesis.md +++ b/docs/api/qiskit/dev/synthesis.md @@ -37,7 +37,7 @@ python_api_name: qiskit.synthesis -`qiskit.synthesis.synth_cnot_count_full_pmh(state, section_size=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/linear/cnot_synth.py "view source code") +`qiskit.synthesis.synth_cnot_count_full_pmh(state, section_size=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/linear/cnot_synth.py "view source code") Synthesize linear reversible circuits for all-to-all architecture using Patel, Markov and Hayes method. @@ -68,7 +68,7 @@ a CX-only circuit implementing the linear transformation. -`qiskit.synthesis.synth_cnot_depth_line_kms(mat)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/linear/linear_depth_lnn.py "view source code") +`qiskit.synthesis.synth_cnot_depth_line_kms(mat)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/linear/linear_depth_lnn.py "view source code") Synthesize linear reversible circuit for linear nearest-neighbor architectures using Kutin, Moulton, Smithline method. @@ -100,7 +100,7 @@ the synthesized quantum circuit. -`qiskit.synthesis.synth_cz_depth_line_mr(mat)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/linear_phase/cz_depth_lnn.py "view source code") +`qiskit.synthesis.synth_cz_depth_line_mr(mat)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/linear_phase/cz_depth_lnn.py "view source code") Synthesis of a CZ circuit for linear nearest neighbour (LNN) connectivity, based on Maslov and Roetteler. @@ -126,7 +126,7 @@ a circuit implementation of the CZ circuit of depth 2\*n+2 for LNN connectivity. -`qiskit.synthesis.synth_cx_cz_depth_line_my(mat_x, mat_z)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/linear_phase/cx_cz_depth_lnn.py "view source code") +`qiskit.synthesis.synth_cx_cz_depth_line_my(mat_x, mat_z)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/linear_phase/cx_cz_depth_lnn.py "view source code") Joint synthesis of a -CZ-CX- circuit for linear nearest neighbour (LNN) connectivity, with 2-qubit depth at most 5n, based on Maslov and Yang. This method computes the CZ circuit inside the CX circuit via phase gate insertions. @@ -152,7 +152,7 @@ a circuit implementation of a CX circuit following a CZ circuit, denoted as a -C -`qiskit.synthesis.synth_cnot_phase_aam(cnots, angles, section_size=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/linear_phase/cnot_phase_synth.py "view source code") +`qiskit.synthesis.synth_cnot_phase_aam(cnots, angles, section_size=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/linear_phase/cnot_phase_synth.py "view source code") This function is an implementation of the GraySynth algorithm of Amy, Azimadeh and Mosca. @@ -207,7 +207,7 @@ the decomposed quantum circuit. -`qiskit.synthesis.synth_permutation_depth_lnn_kms(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/permutation/permutation_lnn.py "view source code") +`qiskit.synthesis.synth_permutation_depth_lnn_kms(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/permutation/permutation_lnn.py "view source code") Synthesize a permutation circuit for a linear nearest-neighbor architecture using the Kutin, Moulton, Smithline method. @@ -229,7 +229,7 @@ the synthesized quantum circuit. -`qiskit.synthesis.synth_permutation_basic(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/permutation/permutation_full.py "view source code") +`qiskit.synthesis.synth_permutation_basic(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/permutation/permutation_full.py "view source code") Synthesize a permutation circuit for a fully-connected architecture using sorting. @@ -251,7 +251,7 @@ the synthesized quantum circuit. -`qiskit.synthesis.synth_permutation_acg(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/permutation/permutation_full.py "view source code") +`qiskit.synthesis.synth_permutation_acg(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/permutation/permutation_full.py "view source code") Synthesize a permutation circuit for a fully-connected architecture using the Alon, Chung, Graham method. @@ -277,7 +277,7 @@ the synthesized quantum circuit. -`qiskit.synthesis.synth_clifford_full(clifford, method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/clifford/clifford_decompose_full.py "view source code") +`qiskit.synthesis.synth_clifford_full(clifford, method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/clifford/clifford_decompose_full.py "view source code") Decompose a Clifford operator into a QuantumCircuit. @@ -306,7 +306,7 @@ a circuit implementation of the Clifford. -`qiskit.synthesis.synth_clifford_ag(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/clifford/clifford_decompose_ag.py "view source code") +`qiskit.synthesis.synth_clifford_ag(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/clifford/clifford_decompose_ag.py "view source code") Decompose a Clifford operator into a QuantumCircuit based on Aaronson-Gottesman method. @@ -330,7 +330,7 @@ a circuit implementation of the Clifford. -`qiskit.synthesis.synth_clifford_bm(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/clifford/clifford_decompose_bm.py "view source code") +`qiskit.synthesis.synth_clifford_bm(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/clifford/clifford_decompose_bm.py "view source code") Optimal CX-cost decomposition of a Clifford operator on 2-qubits or 3-qubits into a QuantumCircuit based on Bravyi-Maslov method. @@ -358,7 +358,7 @@ a circuit implementation of the Clifford. -`qiskit.synthesis.synth_clifford_greedy(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/clifford/clifford_decompose_greedy.py "view source code") +`qiskit.synthesis.synth_clifford_greedy(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/clifford/clifford_decompose_greedy.py "view source code") Decompose a Clifford operator into a QuantumCircuit based on the greedy Clifford compiler that is described in Appendix A of Bravyi, Hu, Maslov and Shaydulin. @@ -388,7 +388,7 @@ a circuit implementation of the Clifford. -`qiskit.synthesis.synth_clifford_layers(cliff, cx_synth_func=, cz_synth_func=, cx_cz_synth_func=None, cz_func_reverse_qubits=False, validate=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/clifford/clifford_decompose_layers.py "view source code") +`qiskit.synthesis.synth_clifford_layers(cliff, cx_synth_func=, cz_synth_func=, cx_cz_synth_func=None, cz_func_reverse_qubits=False, validate=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/clifford/clifford_decompose_layers.py "view source code") Synthesis of a Clifford into layers, it provides a similar decomposition to the synthesis described in Lemma 8 of Bravyi and Maslov. @@ -435,7 +435,7 @@ a circuit implementation of the Clifford. -`qiskit.synthesis.synth_clifford_depth_lnn(cliff)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/clifford/clifford_decompose_layers.py "view source code") +`qiskit.synthesis.synth_clifford_depth_lnn(cliff)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/clifford/clifford_decompose_layers.py "view source code") Synthesis of a Clifford into layers for linear-nearest neighbour connectivity. @@ -465,7 +465,7 @@ a circuit implementation of the Clifford. -`qiskit.synthesis.synth_cnotdihedral_full(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_full.py "view source code") +`qiskit.synthesis.synth_cnotdihedral_full(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_full.py "view source code") Decompose a CNOTDihedral element into a QuantumCircuit. For N \<= 2 qubits this is based on optimal CX cost decomposition from reference \[1]. For N > 2 qubits this is done using the general non-optimal compilation routine from reference \[2]. @@ -490,7 +490,7 @@ a circuit implementation of the CNOTDihedral element. -`qiskit.synthesis.synth_cnotdihedral_two_qubits(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_two_qubits.py "view source code") +`qiskit.synthesis.synth_cnotdihedral_two_qubits(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_two_qubits.py "view source code") Decompose a CNOTDihedral element on a single qubit and two qubits into a QuantumCircuit. This decomposition has an optimal number of CX gates. @@ -518,7 +518,7 @@ a circuit implementation of the CNOTDihedral element. -`qiskit.synthesis.synth_cnotdihedral_general(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_general.py "view source code") +`qiskit.synthesis.synth_cnotdihedral_general(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_general.py "view source code") Decompose a CNOTDihedral element into a QuantumCircuit. @@ -550,7 +550,7 @@ a circuit implementation of the CNOTDihedral element. -`qiskit.synthesis.synth_stabilizer_layers(stab, cz_synth_func=, cz_func_reverse_qubits=False, validate=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/stabilizer/stabilizer_decompose.py "view source code") +`qiskit.synthesis.synth_stabilizer_layers(stab, cz_synth_func=, cz_func_reverse_qubits=False, validate=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/stabilizer/stabilizer_decompose.py "view source code") Synthesis of a stabilizer state into layers. @@ -599,7 +599,7 @@ a circuit implementation of the stabilizer state. -`qiskit.synthesis.synth_stabilizer_depth_lnn(stab)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/stabilizer/stabilizer_decompose.py "view source code") +`qiskit.synthesis.synth_stabilizer_depth_lnn(stab)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/stabilizer/stabilizer_decompose.py "view source code") Synthesis of an n-qubit stabilizer state for linear-nearest neighbour connectivity, in 2-qubit depth 2\*n+2 and two distinct CX layers, using CX and phase gates (S, Sdg or Z). @@ -624,7 +624,7 @@ a circuit implementation of the stabilizer state. -`qiskit.synthesis.synth_circuit_from_stabilizers(stabilizers, allow_redundant=False, allow_underconstrained=False, invert=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/stabilizer/stabilizer_circuit.py "view source code") +`qiskit.synthesis.synth_circuit_from_stabilizers(stabilizers, allow_redundant=False, allow_underconstrained=False, invert=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/stabilizer/stabilizer_circuit.py "view source code") Synthesis of a circuit that generates a state stabilized by the stabilziers using Gaussian elimination with Clifford gates. If the stabilizers are underconstrained, and allow\_underconstrained is True, the circuit will output one of the states stabilized by the stabilizers. Based on stim implementation. @@ -662,7 +662,7 @@ a circuit that generates a state stabilized by stabilizers. -`qiskit.synthesis.generate_basic_approximations(basis_gates, depth, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/discrete_basis/generate_basis_approximations.py "view source code") +`qiskit.synthesis.generate_basic_approximations(basis_gates, depth, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/discrete_basis/generate_basis_approximations.py "view source code") Generates a list of `GateSequence``s with the gates in ``basic_gates`. @@ -690,7 +690,7 @@ List of `GateSequences` using the gates in `basic_gates`. -`qiskit.synthesis.synth_qft_line(num_qubits, do_swaps=True, approximation_degree=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/qft/qft_decompose_lnn.py "view source code") +`qiskit.synthesis.synth_qft_line(num_qubits, do_swaps=True, approximation_degree=0)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/qft/qft_decompose_lnn.py "view source code") Synthesis of a QFT circuit for a linear nearest neighbor connectivity. Based on Fig 2.b in Fowler et al. \[1]. @@ -722,7 +722,7 @@ Decomposition of general $2^n \times 2^n$ unitary matrices for any number of qub -`qiskit.synthesis.qs_decomposition(mat, opt_a1=True, opt_a2=True, decomposer_1q=None, decomposer_2q=None, *, _depth=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/qsd.py "view source code") +`qiskit.synthesis.qs_decomposition(mat, opt_a1=True, opt_a2=True, decomposer_1q=None, decomposer_2q=None, *, _depth=0)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/qsd.py "view source code") Decomposes a unitary matrix into one and two qubit gates using Quantum Shannon Decomposition, diff --git a/docs/api/qiskit/dev/synthesis_aqc.md b/docs/api/qiskit/dev/synthesis_aqc.md index 3a3699082f6..278ff3330ae 100644 --- a/docs/api/qiskit/dev/synthesis_aqc.md +++ b/docs/api/qiskit/dev/synthesis_aqc.md @@ -129,7 +129,7 @@ This uses a helper function, [`make_cnot_network`](#qiskit.synthesis.unitary.aqc -`qiskit.synthesis.unitary.aqc.make_cnot_network(num_qubits, network_layout='spin', connectivity_type='full', depth=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/synthesis/unitary/aqc/cnot_structures.py "view source code") +`qiskit.synthesis.unitary.aqc.make_cnot_network(num_qubits, network_layout='spin', connectivity_type='full', depth=0)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/synthesis/unitary/aqc/cnot_structures.py "view source code") Generates a network consisting of building blocks each containing a CNOT gate and possibly some single-qubit ones. This network models a quantum operator in question. Note, each building block has 2 input and outputs corresponding to a pair of qubits. What we actually return here is a chain of indices of qubit pairs shared by every building block in a row. diff --git a/docs/api/qiskit/dev/transpiler.md b/docs/api/qiskit/dev/transpiler.md index 555d9a6e4f2..8882d1aa576 100644 --- a/docs/api/qiskit/dev/transpiler.md +++ b/docs/api/qiskit/dev/transpiler.md @@ -935,7 +935,7 @@ See [https://arxiv.org/abs/2102.01682](https://arxiv.org/abs/2102.01682) for mor -`qiskit.transpiler.TranspilerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/exceptions.py "view source code") +`qiskit.transpiler.TranspilerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/exceptions.py "view source code") Exceptions raised during transpilation. @@ -945,7 +945,7 @@ Set the error message. -`qiskit.transpiler.TranspilerAccessError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/exceptions.py "view source code") +`qiskit.transpiler.TranspilerAccessError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/exceptions.py "view source code") DEPRECATED: Exception of access error in the transpiler passes. @@ -955,7 +955,7 @@ Set the error message. -`qiskit.transpiler.CouplingError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/exceptions.py "view source code") +`qiskit.transpiler.CouplingError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/exceptions.py "view source code") Base class for errors raised by the coupling graph object. @@ -965,7 +965,7 @@ Set the error message. -`qiskit.transpiler.LayoutError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/exceptions.py "view source code") +`qiskit.transpiler.LayoutError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/exceptions.py "view source code") Errors raised by the layout object. @@ -975,7 +975,7 @@ Set the error message. -`qiskit.transpiler.CircuitTooWideForTarget(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/exceptions.py "view source code") +`qiskit.transpiler.CircuitTooWideForTarget(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/exceptions.py "view source code") Error raised if the circuit is too wide for the target. @@ -985,7 +985,7 @@ Set the error message. -`qiskit.transpiler.InvalidLayoutError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/exceptions.py "view source code") +`qiskit.transpiler.InvalidLayoutError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/exceptions.py "view source code") Error raised when a user provided layout is invalid. diff --git a/docs/api/qiskit/dev/transpiler_passes.md b/docs/api/qiskit/dev/transpiler_passes.md index e04f4c486da..55d5de5af13 100644 --- a/docs/api/qiskit/dev/transpiler_passes.md +++ b/docs/api/qiskit/dev/transpiler_passes.md @@ -95,7 +95,7 @@ python_api_name: qiskit.transpiler.passes -`qiskit.transpiler.passes.rzx_templates(template_list=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/passes/calibration/rzx_templates.py "view source code") +`qiskit.transpiler.passes.rzx_templates(template_list=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/passes/calibration/rzx_templates.py "view source code") Convenience function to get the cost\_dict and templates for template matching. diff --git a/docs/api/qiskit/dev/transpiler_plugins.md b/docs/api/qiskit/dev/transpiler_plugins.md index 500e9542cda..ab9b8393b1a 100644 --- a/docs/api/qiskit/dev/transpiler_plugins.md +++ b/docs/api/qiskit/dev/transpiler_plugins.md @@ -99,7 +99,7 @@ There isn’t a limit to the number of plugins a single package can include as l -`qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins(stage_name)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") +`qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins(stage_name)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") Get a list of installed plugins for a stage. @@ -123,7 +123,7 @@ plugins -`qiskit.transpiler.preset_passmanagers.plugin.passmanager_stage_plugins(stage)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") +`qiskit.transpiler.preset_passmanagers.plugin.passmanager_stage_plugins(stage)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") Return a dict with, for each stage name, the class type of the plugin. diff --git a/docs/api/qiskit/dev/transpiler_preset.md b/docs/api/qiskit/dev/transpiler_preset.md index e7edb6b284d..c57125ffdd9 100644 --- a/docs/api/qiskit/dev/transpiler_preset.md +++ b/docs/api/qiskit/dev/transpiler_preset.md @@ -28,7 +28,7 @@ This module contains functions for generating the preset pass managers for the t -`qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager(optimization_level, backend=None, target=None, basis_gates=None, inst_map=None, coupling_map=None, instruction_durations=None, backend_properties=None, timing_constraints=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, approximation_degree=1.0, seed_transpiler=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None, init_method=None, optimization_method=None, *, _skip_target=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/__init__.py "view source code") +`qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager(optimization_level, backend=None, target=None, basis_gates=None, inst_map=None, coupling_map=None, instruction_durations=None, backend_properties=None, timing_constraints=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, approximation_degree=1.0, seed_transpiler=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None, init_method=None, optimization_method=None, *, _skip_target=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/__init__.py "view source code") Generate a preset [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") @@ -101,7 +101,7 @@ The preset pass manager for the given options -`qiskit.transpiler.preset_passmanagers.level_0_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/level0.py "view source code") +`qiskit.transpiler.preset_passmanagers.level_0_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/level0.py "view source code") Level 0 pass manager: no explicit optimization other than mapping to backend. @@ -129,7 +129,7 @@ a level 0 pass manager. -`qiskit.transpiler.preset_passmanagers.level_1_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/level1.py "view source code") +`qiskit.transpiler.preset_passmanagers.level_1_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/level1.py "view source code") Level 1 pass manager: light optimization by simple adjacent gate collapsing. @@ -155,7 +155,7 @@ a level 1 pass manager. -`qiskit.transpiler.preset_passmanagers.level_2_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/level2.py "view source code") +`qiskit.transpiler.preset_passmanagers.level_2_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/level2.py "view source code") Level 2 pass manager: medium optimization by initial layout selection and gate cancellation using commutativity rules. @@ -183,7 +183,7 @@ a level 2 pass manager. -`qiskit.transpiler.preset_passmanagers.level_3_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/level3.py "view source code") +`qiskit.transpiler.preset_passmanagers.level_3_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/level3.py "view source code") Level 3 pass manager: heavy optimization by noise adaptive qubit mapping and gate cancellation using commutativity rules and unitary synthesis. @@ -215,7 +215,7 @@ a level 3 pass manager. -`qiskit.transpiler.preset_passmanagers.common.generate_control_flow_options_check(layout_method=None, routing_method=None, translation_method=None, optimization_method=None, scheduling_method=None, basis_gates=(), target=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_control_flow_options_check(layout_method=None, routing_method=None, translation_method=None, optimization_method=None, scheduling_method=None, basis_gates=(), target=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate a pass manager that, when run on a DAG that contains control flow, fails with an error message explaining the invalid options, and what could be used instead. @@ -231,7 +231,7 @@ a pass manager that populates the `contains_x` properties for each of the contro -`qiskit.transpiler.preset_passmanagers.common.generate_error_on_control_flow(message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_error_on_control_flow(message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Get a pass manager that always raises an error if control flow is present in a given circuit. @@ -239,7 +239,7 @@ Get a pass manager that always raises an error if control flow is present in a g -`qiskit.transpiler.preset_passmanagers.common.generate_unroll_3q(target, basis_gates=None, approximation_degree=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_unroll_3q(target, basis_gates=None, approximation_degree=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate an unroll >3q [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") @@ -264,7 +264,7 @@ The unroll 3q or more pass manager -`qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager(coupling_map)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager(coupling_map)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate a layout embedding [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") @@ -288,7 +288,7 @@ set has been set in earlier stages -`qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager(routing_pass, target, coupling_map=None, vf2_call_limit=None, backend_properties=None, seed_transpiler=None, check_trivial=False, use_barrier_before_measurement=True, vf2_max_trials=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager(routing_pass, target, coupling_map=None, vf2_call_limit=None, backend_properties=None, seed_transpiler=None, check_trivial=False, use_barrier_before_measurement=True, vf2_max_trials=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate a routing [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") @@ -316,7 +316,7 @@ The routing pass manager -`qiskit.transpiler.preset_passmanagers.common.generate_pre_op_passmanager(target=None, coupling_map=None, remove_reset_in_zero=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_pre_op_passmanager(target=None, coupling_map=None, remove_reset_in_zero=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate a pre-optimization loop [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") @@ -340,7 +340,7 @@ The pass manager -`qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager(target, basis_gates=None, method='translator', approximation_degree=None, coupling_map=None, backend_props=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager(target, basis_gates=None, method='translator', approximation_degree=None, coupling_map=None, backend_props=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate a basis translation [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") @@ -372,7 +372,7 @@ The basis translation pass manager -`qiskit.transpiler.preset_passmanagers.common.generate_scheduling(instruction_durations, scheduling_method, timing_constraints, inst_map, target=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/transpiler/preset_passmanagers/common.py "view source code") +`qiskit.transpiler.preset_passmanagers.common.generate_scheduling(instruction_durations, scheduling_method, timing_constraints, inst_map, target=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/common.py "view source code") Generate a post optimization scheduling [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") diff --git a/docs/api/qiskit/dev/utils.md b/docs/api/qiskit/dev/utils.md index ed7fde56b07..9e276b769c4 100644 --- a/docs/api/qiskit/dev/utils.md +++ b/docs/api/qiskit/dev/utils.md @@ -22,7 +22,7 @@ python_api_name: qiskit.utils -`qiskit.utils.add_deprecation_to_docstring(func, msg, *, since, pending)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/deprecation.py "view source code") +`qiskit.utils.add_deprecation_to_docstring(func, msg, *, since, pending)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/deprecation.py "view source code") Dynamically insert the deprecation message into `func`’s docstring. @@ -37,7 +37,7 @@ Dynamically insert the deprecation message into `func`’s docstring. -`qiskit.utils.deprecate_arg(name, *, since, additional_msg=None, deprecation_description=None, pending=False, package_name='qiskit', new_alias=None, predicate=None, removal_timeline='no earlier than 3 months after the release date')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/deprecation.py "view source code") +`qiskit.utils.deprecate_arg(name, *, since, additional_msg=None, deprecation_description=None, pending=False, package_name='qiskit', new_alias=None, predicate=None, removal_timeline='no earlier than 3 months after the release date')`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/deprecation.py "view source code") Decorator to indicate an argument has been deprecated in some way. @@ -67,7 +67,7 @@ Callable -`qiskit.utils.deprecate_arguments(kwarg_map, category=, *, since=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/deprecation.py "view source code") +`qiskit.utils.deprecate_arguments(kwarg_map, category=, *, since=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/deprecation.py "view source code") Deprecated. Instead, use @deprecate\_arg. @@ -89,7 +89,7 @@ Callable -`qiskit.utils.deprecate_func(*, since, additional_msg=None, pending=False, package_name='qiskit', removal_timeline='no earlier than 3 months after the release date', is_property=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/deprecation.py "view source code") +`qiskit.utils.deprecate_func(*, since, additional_msg=None, pending=False, package_name='qiskit', removal_timeline='no earlier than 3 months after the release date', is_property=False)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/deprecation.py "view source code") Decorator to indicate a function has been deprecated. @@ -118,7 +118,7 @@ Callable -`qiskit.utils.deprecate_function(msg, stacklevel=2, category=, *, since=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/deprecation.py "view source code") +`qiskit.utils.deprecate_function(msg, stacklevel=2, category=, *, since=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/deprecation.py "view source code") Deprecated. Instead, use @deprecate\_func. @@ -141,7 +141,7 @@ Callable -`qiskit.utils.local_hardware_info()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/multiprocessing.py "view source code") +`qiskit.utils.local_hardware_info()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/multiprocessing.py "view source code") Basic hardware information about the local machine. @@ -159,7 +159,7 @@ The hardware information. -`qiskit.utils.is_main_process()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/multiprocessing.py "view source code") +`qiskit.utils.is_main_process()`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/multiprocessing.py "view source code") Checks whether the current process is the main one @@ -167,7 +167,7 @@ Checks whether the current process is the main one -`qiskit.utils.apply_prefix(value, unit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/units.py "view source code") +`qiskit.utils.apply_prefix(value, unit)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/units.py "view source code") Given a SI unit prefix and value, apply the prefix to convert to standard SI unit. @@ -200,7 +200,7 @@ Converted value. -`qiskit.utils.detach_prefix(value, decimal=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/units.py "view source code") +`qiskit.utils.detach_prefix(value, decimal=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/units.py "view source code") Given a SI unit value, find the most suitable prefix to scale the value. @@ -244,7 +244,7 @@ A tuple of scaled value and prefix. -`qiskit.utils.wrap_method(cls, name, *, before=None, after=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/classtools.py "view source code") +`qiskit.utils.wrap_method(cls, name, *, before=None, after=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/classtools.py "view source code") Wrap the functionality the instance- or class method `cls.name` with additional behaviour `before` and `after`. @@ -271,7 +271,7 @@ A helper function for calling a custom function with python [`ProcessPoolExecuto -`qiskit.utils.parallel_map(task, values, task_args=(), task_kwargs={}, num_processes=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/parallel.py "view source code") +`qiskit.utils.parallel_map(task, values, task_args=(), task_kwargs={}, num_processes=2)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/parallel.py "view source code") Parallel execution of a mapping of values to the function task. This is functionally equivalent to: @@ -383,7 +383,7 @@ from qiskit.utils import LazyImportTester -`qiskit.utils.LazyDependencyManager(*, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/lazy_tester.py "view source code") +`qiskit.utils.LazyDependencyManager(*, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/lazy_tester.py "view source code") A mananger for some optional features that are expensive to import, or to verify the existence of. @@ -512,7 +512,7 @@ Eagerly attempt to import the dependencies in this object, and raise an exceptio -`qiskit.utils.LazyImportTester(name_map_or_modules, *, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/lazy_tester.py "view source code") +`qiskit.utils.LazyImportTester(name_map_or_modules, *, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/lazy_tester.py "view source code") A lazy dependency tester for importable Python modules. Any required objects will only be imported at the point that this object is tested for its Boolean value. @@ -526,7 +526,7 @@ A lazy dependency tester for importable Python modules. Any required objects wil -`qiskit.utils.LazySubprocessTester(command, *, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/utils/lazy_tester.py "view source code") +`qiskit.utils.LazySubprocessTester(command, *, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/utils/lazy_tester.py "view source code") A lazy checker that a command-line tool is available. The command will only be run once, at the point that this object is checked for its Boolean value. diff --git a/docs/api/qiskit/dev/visualization.md b/docs/api/qiskit/dev/visualization.md index 977ab9cea27..285edeb0200 100644 --- a/docs/api/qiskit/dev/visualization.md +++ b/docs/api/qiskit/dev/visualization.md @@ -227,7 +227,7 @@ You can find code examples for each visualization functions on the individual fu -`qiskit.visualization.VisualizationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/1.0/qiskit/visualization/exceptions.py "view source code") +`qiskit.visualization.VisualizationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/main/qiskit/visualization/exceptions.py "view source code") For visualization specific errors. diff --git a/public/api/qiskit/dev/objects.inv b/public/api/qiskit/dev/objects.inv index d78c319b6e8434ba63050199bf9d6c14e49c9092..cb2d5aa1683e685d730ecb7a2f4c645a67c11b15 100644 GIT binary patch delta 34159 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%0AV?VIzNM?;@~az{Ap12?(%Te)+F>xf{jPfZ2q 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 GZlD`^m!iD@ diff --git a/public/images/api/qiskit/dev/circuit-1.png b/public/images/api/qiskit/dev/circuit-1.png index c75b790b80b9054b43f5cfb7f5bf0ba942a9df36..b31f60b8158f0962a6c5b0360e0cba2490ab5764 100644 GIT binary patch delta 43 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 GH~$0cT0Y7E literal 9082 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 aaW+5OGQx5&sQSxJk$W diff --git a/public/images/api/qiskit/dev/circuit_library-1.png b/public/images/api/qiskit/dev/circuit_library-1.png index 9fb79cf8bb176f64369851dc6eef9f9c7b324b57..65ffa80474267b59d83f46adea8dfa00ee473468 100644 GIT binary patch delta 43 zcmbPeIMHx|n}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5-;s@JQVIY^Ob{~w delta 43 ycmZp0Y;c_5reLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*OplmY-hVh;8I diff --git a/public/images/api/qiskit/dev/providers_fake_provider-1_00.png b/public/images/api/qiskit/dev/providers_fake_provider-1_00.png index 7dc1e7b38793b2707f50f46a3fa4d70ff5c408c6..824e5d397e2a6ab9b33e2fa3aac894a02bcd097c 100644 GIT binary patch delta 43 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 P10;%=?A7GUx_|x)(FJJ5 literal 13803 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 E0CjBO3DZ#pdcN?fYi{SQqrA6 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 literal 10554 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

s^ofy-;a>S< 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%0A$_8AOECNShJ}17UQI=yL-S+scpJ_ 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 literal 19154 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 literal 16234 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 Y7=yx{ZV^S;PDV5?Ur{Mlvb^)(09al)kpKVy literal 11217 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 V>B<29D2&%4nyOb+UMX4L{~w}?oh$$V diff --git a/public/images/api/qiskit/dev/pulse-7.png b/public/images/api/qiskit/dev/pulse-7.png index 8b2d9f28b638eb66d9513dd45131e981a36f5a61..ffccfc69dd7c61792d52f8ff8d8039e55b67b5a8 100644 GIT binary patch literal 14059 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 U&|!$c2hR{Cx$CkyGDZ*oKkQBKK>z>% literal 14079 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 diff --git a/public/images/api/qiskit/dev/qasm3-1.png b/public/images/api/qiskit/dev/qasm3-1.png index b3b93ef79db266c59a9a94be86e17b29c74aec25..d80ef309427d4113dfc19e7ffc049ae0477ad76d 100644 GIT binary patch delta 45 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 literal 6414 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 Tv#^5yCLsA|%F-p0#zFrC3&SQ_ diff --git a/public/images/api/qiskit/dev/qiskit-circuit-ControlledGate-2.png b/public/images/api/qiskit/dev/qiskit-circuit-ControlledGate-2.png index 5400e72528cb8ff4ff90827408460515b4962986..0069c5eb20f6ce84e57496442439c77117be0857 100644 GIT binary patch literal 7288 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 diff --git a/public/images/api/qiskit/dev/qiskit-circuit-InstructionSet-1.png b/public/images/api/qiskit/dev/qiskit-circuit-InstructionSet-1.png index 5c1e13a47690b5f736ff2ba0dc231613202aa187..6ef86b54517d27b3911ee0cfdaba148784ad2b87 100644 GIT binary patch literal 8936 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

GCp#v!PlcRFm}I-#LN3r(7rQs{ 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 diff --git a/public/images/api/qiskit/dev/qiskit-circuit-Operation-1.png b/public/images/api/qiskit/dev/qiskit-circuit-Operation-1.png index 7736ef92c716463cee93c9e531a3ca5c5512bc2b..fa8a838827f24fae53698e0930c41982eee645fb 100644 GIT binary patch delta 43 zcmeya`(1Z}n}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5JTXa diff --git a/public/images/api/qiskit/dev/qiskit-circuit-Parameter-1_00.png b/public/images/api/qiskit/dev/qiskit-circuit-Parameter-1_00.png index d2e775ef9b9d0d2164b0daaf4e77cb4c89023b84..ac09c7c62285759505167ce937b7932dadd1499d 100644 GIT binary patch delta 43 zcmbQqJCk>Un}UU&k&Z$}Nl8JmmA-y%Vo5Un}WHXiH<@>Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5Nl8JmmA-y%Vo52PG*u`eo?x2PG*u`eo?xrb5>@8n}UU&k&Z$}Nl8JmmA-y%Vo5rb5>@8n}WHXiH<@>Nl8JmmA-y%Vo5n}UU&k&Z$}Nl8JmmA-y%Vo5a delta 43 ycmdlivsq?>n}WHXiH<@>Nl8JmmA-y%Vo5-;s@Jvv~nLwGdeV delta 43 ycmZpaX_T4ZreLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*PUY+e8~%MTm? diff --git a/public/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-4_01.png b/public/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-4_01.png index cdf4f6006239cb3033d0c8eec21e15483e0c398f..ce1d6a93f9b0b337cb6f125559799d02f4806b5b 100644 GIT binary patch delta 43 zcmX>pcT#SGn}UU&k&Z$}Nl8JmmA-y%Vo5~-dRf-Wd delta 43 ycmX>pcT#SGn}WHXiH<@>Nl8JmmA-y%Vo5-;s@J8ax0$91r;b delta 43 ycmeB^?30|}reLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*Op1`hx?G7h`| diff --git a/public/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-6.png b/public/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-6.png index f5ed5c047940f54658b7a09e07b2643564b38434..314d3812a0696f46e2d0a142996c437162e6f917 100644 GIT binary patch delta 43 zcmZ3WxIl4&n}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo52PG*u`eo?x2PG*u`eo?xb%7 diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-AND-2.png b/public/images/api/qiskit/dev/qiskit-circuit-library-AND-2.png index 4504ff63484f731657884621691157d6d949665a..6a689868b9128e315b82cacf2a6f39333a9dcd95 100644 GIT binary patch delta 45 zcmX@#$#}k#ae|wIg`Sa)LPkkRL9vy-er{q(K~8>2PG*u`eo?x2PG*u`eo?xNl8JmmA-y%Vo5-;s@J^NayjH4z{H delta 43 ycmZq4Xvvu1reLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*PUJYxV(OAq4! diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-GR-1.png b/public/images/api/qiskit/dev/qiskit-circuit-library-GR-1.png index 8a88cf0a2a9adbe3966a6c7a420f52ea656a93a6..21b44d271d89d895b120a94fdcfdca5c8f19b699 100644 GIT binary patch delta 45 zcmZ3{!nmS^ae|wIg`Sa)LPkkRL9vy-er{q(K~8>2PG*u`eo?x2PG*u`eo?x2PG*u`eo?xX0sw`3 B5*`2m delta 45 zcmaFU%=o66ae|wIxt@uRLPkkRL9vy-er{q(K~8>2PG*u`eo?x2PG*u`eo?x2PG*u`eo?xNl8JmmA-y%Vo5Nl8JmmA-y%Vo5n}UU&k&Z$}Nl8JmmA-y%Vo5n}WHXiH<@>Nl8JmmA-y%Vo5x=+X1`rMa diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-IQP-1.png b/public/images/api/qiskit/dev/qiskit-circuit-library-IQP-1.png index 02a1fa1eb3b80353d57f4a6163180a4385789c3e..ab4aa2765286db1f85d3e70a1d9409ff030ae687 100644 GIT binary patch delta 43 zcmX?VeAIY?n}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5i4G*FK diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-IQP-2.png b/public/images/api/qiskit/dev/qiskit-circuit-library-IQP-2.png index 27b33e02d602bb2e6ad20d4249c1559e95a0b482..6d2b8bf43dd93b355db30cf5c5726dedb336ff61 100644 GIT binary patch delta 43 zcmaD{_PA_Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5GIa_z)fd diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-Permutation-1.png b/public/images/api/qiskit/dev/qiskit-circuit-library-Permutation-1.png index b5d151096b844028b471aa286fada6dc2c350bd0..5a55d908669390410bbb114ffe186b8a7bb997b8 100644 GIT binary patch delta 43 zcmX@+cFb*pn}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5y diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-Permutation-2.png b/public/images/api/qiskit/dev/qiskit-circuit-library-Permutation-2.png index 7e991ea0b41af472378f50971e86277aaf96838a..1d04af7412dcf171cc3b07bc291f0b858d901c9a 100644 GIT binary patch delta 45 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 diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-PhaseEstimation-1.png b/public/images/api/qiskit/dev/qiskit-circuit-library-PhaseEstimation-1.png index 7c5e890d742d3fc863831342157c0e1340f4252b..3b6465a7130b800af1cdf1260c3d8c11a08af97c 100644 GIT binary patch literal 12208 zcmeHtXIN8PpYH|~Y@i@h1m-qA%`M8xi&HwZg8TZ$ZGY`%v^b~@fLa6yngYUmFW!99o%K}5JQ*Zixq0Y#ei*a=8r?-(y`w z=#1L(O0&M+-VX(5RS=}+v}&vg^ecm~4Sw&r4!>%y{C|G=b7Ybk!3f5PWA)tZgGXJg z=|ZL5&D1{?5XZNVoeEu-ZiKXV4pzFzu&cxl&kX;Dv>em#E^o{KA)b)Ofn)OLmGS0R zO5aOe-%5WRq7C2pkG~Kk@UVMcL^~pj9TGp6MR%k%dV$L^XAPUQ|~Ep*Qp-e(ysu+?!+)c!-spYlil|fQvnU1P)jMWUW zp6Yb#O<@DG~McovRk9CQL22blN+Y%5g(FqLQ2YDczC#{$U5us=8|$w;kO=dOI5~TGy^%fi(E$4wzIN!Vr1z@WwWt+eMv>{+Fc8L zEHUww`j*u)nJ%a1U6;O|vGbnP)qNQ$Lq3Z{zSvNRUZO;#TvT%Y`K|v;_ptHB5ajh! z_&zws(o|1@`Lm{2spPRStJL&#n?)Lx>!L-Fv9a;XsHn`t7cIs*GPR}gW6!6{esFBx zzTFyq1bS*%Vw*YMo^Iy6>gVStC@h@2FtAk3GCY{QDv(a0XmfTO7Pq=9Sdx4qUc5;B zQ%s4q&p$^-(pKk3g)UssgsCB> zNV$wyy?wBKZg#e{%;^VysD>$+N7j&p&FkDPQu(^O(9+CpHF7N}K0&%luas$x!4RT{ z5xP989}hj0NzfYDyvdkQGa-*Ter9vFes^E$^>KrXV;AD&@W%aqzn|G+B;oNcS<&uG z)NVd;f*Zze1sZT*C~=qxGa+6M1o>Vk7HGTT@sn*r251d_G#Jv`*%F9hwKJWSC z{FVIteDs~(61(vD_*{Q~B+zV|NC7&qNE zudqZEUs5oz(T+8FT)Pj^P}thsSX>=VzESejUT;1mC+3hgmPa5(7$YMPK+ve6W z6eL-{b0K0ogr|IMsNKz}Re7~GOvr(Ku;XBXB9G*VoAfZ8cOOSOn3)jv2jOu-+%l%~tF+g@Bj=gYk)iW<>qElL^Ho^=CzzNJ z4sA`%(O2q%kA%N`$&WFtz-LB_+oYY*PO}2+ zJJO!)){WIZCT^W{4U<5#Tpha=x?6^T$;!~U-MN#yzp}Sn z;adfMt;NZl|0LE^eg!Mv9xuPH!q}oSa0A^~`$pNRghTg^QYG>T8I>DRYa@$$Nt5ff zmi1?55@o30>z14s=QQ50f1*ik3iq$oD@}O0NHY6p?b^M&*rJhZb#*l}JNu@+y?wMi zq58K22f|;yI*p0GXc_YRS^ZaGuxb=F>+F&u3W>%k1fY|6MF2dSVX(-zVYFD>n3(Rv~0OmRki1(%? zxOb0s_87hR@jlB@Hfo$FaYCYCXjCe_Q z^l99I4&C%69<4f=n2ub6IsjuJZ~Kvkh*$6gyYP&zml*E`0GE7)5G2hBVa*2#7A z;$lJ$A=;*f@r4amFGC1R#U<}4Dc`j@Lyi?M(z8P))~`)BmUAG~LW`EW(!OJ5l|99J zUEZu8sqNR&mn>79AWE9)DNNcA+=2!z(JXc0VGibL-aY&O9^vq^Q5L zkKN{6@v6{7ZFBc(a??SJc#Yd5PlVKd*vw-mYMO{Cyw$QveH}r{36{Py265D7ZB*6J zF!ngb@VM$iM@|&F{()j@Ot1fRw5A)8>f`{%xJ`E>ulx~z*836Fhz8~V0lZ{N>*mXg zmWO}8iezkOM!2>K$&~8#Bi80Sk>c7j@OdDw{A+`_W%MFG4E{tMWse~>w*>_Se}4b| zeNq%bs5Rn9Sqc!25RiM0QEBJL7ktz-)gvF?zaJ~^GS%+NHF0g0UAFrE{)w`RiZLqLk5fPEVuGx|0s9lTp=Zr{~yqve}t2)S`wOvd#7dWan@|UVA6e9#&xqeIgxP8{y zy3J#=X<_GhZmzr1$3{}7n}~;!`KWTNNt?L!Wy)d6o6gP!pBoyAt=ms3C@Kn`K79k$ z^51|b?)>uxrmZbiC7ei1;^3D48}PEjyauGa^z(Su^sEEYC+@8xxhB)`TQt&OPDd2o z1rK_RBd0rUgRoZ9Z7!t~s#z-NIxFw$vB9yb5FkyCwW-^W=;XUi8QKk2n;4bYwnkmF zJjl(Rv#@~AF|9JZTNm`=*|TS&7cYw6t=khP?Wzo#rj6UZFY)#3V^zxo-aQlo#jw;q zr=G|A%kjm&|FzvY40w=wnN@{o<+)u`c@0mM@wN>-0hdKTdn!-^6!B39fPoMG{yVNQ zT6}JPUfaMRs;{q4jIik=aPp)e$OEF7Wz*4f`fskt$;oj^*vE1lm3-ZrtVD9B51<UpSo@TiT|h}WJ7b-u45k3*btWtfER4vr2OnF>!6Q$$I| zq)UVhvz7JMPvIuysOkNc<4~-qet6@M@Dc9W3A3E z`0vfTu0P*2#WlRP6S3OYXCXfdO$-qq3p6>q?R0(c?{fd2&;N&}eq9=$ZNOdc557<9 zK5t*r#Pi9??XX*Vq1s2Xk&N zcJh-q*>iZ5ZpBWp{RrwAItY#a6J~~@8)K!kW!xq;($(U`tXht##z|AV1(=ZB2Z+B- zfqBF4o?c!!An9mHr=$lD9>khx1+P59W4p+FKS!uKWX{Uu0vCZM;Y`gtznYJR=5s&w z6x#sfox(V~x`va<Crp>kf@ zeL9=d)Z@=W%jW9I%YWlec|ro#~j>Qp7SG_ zx+J|O;T%J?DcKZQfl}lk#n8XM8Cba+>grexjpwZFTq%D(WR)TxMQU{SAw&CKym;|6 zCiXE(pg33(|)P7Yx&w$I7 zG2=eBU+`z@?v*d5eLGcNrn9!%TPoigMK7H2*hWgf5ISEiKp&5xtQ!sV%XH43HZ{4+ zGis`>DCp8yBF*!*E)YSC6}$F->zSV;FHubS$7deL310Tm8g2f4VrWo8$8YR&X#4|x zkFhe49C%zaf$H+^Ji|;#egqU7TSQ)@duRx*CoKSWHZ^2)>tv{2Y8^OD|0_QwIod*(mWq>oT&xa=R3-Dv@r4U09>dl|+B!p1!5 zh=0S%bTT(OH%|))D}xe3XTxKq&y`xJQeDq%R~}MV&c78@ z9lKm2t;pJttXt@Hq`9sJGA2W%8cEKCxR9($@4nZsrc{m=oUL2^d{n$MXg*wOPNx5r zBO1D~?1x|H_c8saOQ$2pa=X7oT`ay^&*4hzz<>#DgJ>bn1Rz}ye8PXkOlNm@bki5A zWbFqhHP(sc(Tx07DoK8+82sw4tI0`G zF4?+rzw=EQJDHJOjGtdMWIt+ZAtkomNxk;usS4=pEx}x-8u2H=!PE@RkI2sKdK0N+QT)tQE{}<}Kl`<07D@A_9+VJ9TEr5A) zT_7-9-Dq1G`#zWyr~kv${MQrqKd=7F8vdUl`JW;AZ{Y3!ZfQI>QnfrSEUag3ZEe!Q z%$Avvp%HfSo(yvSNnl{$Wm#F0tZy*$6(^_s3U_+$fm3Q7W#>B*Ah60xNqOIG4xU#N zg3$1&D1)he8p();pG{&G)B1=o%b9Pq&r3&4L&Q1l z+qV| z6zaC-!sj*S@ z8K;OI9$%!Ft)FPNwbn%&s3Q9spd4Y7S2glJ$0^%zyFU$m67u(#U|BEO^?WQiTg8|r zgTvK^R8)jKFCruq7GusNwGJZej`~kMvE|h80$>eiB7Mz@pNjb zgV{M?7kHQY>cZWFzx|ff(xM@|wLVW2UKcg<96rSGviR~U5lkQk4Uf~*6LKdfZNbi} z#7H1UTffHnUHM#TKcEni0%d3J&BrZf! z))g9KBqI5t>#8DE3q-IX+U9F;uMkif*qto8R$NjOa}CzaHx**+)wMM}o3#fIn76aB zO_1`c+ZM*#7l$71%`&6-^^`g!EKT>L#8=rfVLw=1g@(FltsyN9*Ii&98RxdSzH0d9 z*8Po^RfXK#T*GqbRJW;~)D6Zm35hkWzqJWN~T z=D_E0AvE~0>n>0j7#Q$^VL|`P7?rR7+(xAqf1W5P5XEplcz?0^a`MW`icQvjMB}3G z+CuqHztaK&3UA-Oom*PU#k2cc(og5G3^?Q!LZCU2Eh~tLB(9`)6 ztJbTf{cbU)UgH7`Z}6Z?!_!~$uMzRIjx!K_O%oetmX`GX{PWLZ+~WLv`_E5d;*iTQ zyuq{1EiQ(amX@Ls@tqG(apxw|(fKuRh&Ur6qE5tbu6s@a5a=~9BRXbRuK4>c6(*dK zlQUINP#_8$yDTlVt7Cg8ud>v5IhRW*8>+W&-+ubnUmA{%ZvX>RVY`2>uOH2tuU_ml z0%slh;Ne5_!tNscxE4ms$EVWS*%?3IC}Fd{GRt-TR*k?YuQWbGSy}lY7nfJ}GlXCZ z>pnb}UwqM_nni%ai2$UJHdk=N-ayArX)6{$bor`f)Wmpq^cL%O;OF3Vc z81Ueu@F6Qto<7}$rVG4;_598Gge{$k(AEhByQOCKkrP*d1hm3VsunqZy9&Y1t(FT= z)@Gs7cGRG0R-Z)Z<8LdoKZq;bO#T??n9XJN;9RDaZ-Km!Iw?sviaP=T7TK~QwPJQX zI;YfPHK2?{688-bLBy=vt^>Z|qit%&Sa%>JB#79Wp!Y-Dw?}To>-VH>c-ab{Rp7hm&~+e)~y2o+Eah}&VJw&f+`byO(^MTX={f^ zNB3m#u?PS#Q4=C{RV{=-7Gcec3zpe4HcZPF&A#MC2Xx*qT5|P zK`y*P#Kb3QaOf>M?US-G?QLyh5J5owRPf}<$Ge9Rr0l6QI|3uZCF%J3lEXkYk@%ar zg#~SzOz(Wbrv&}a1|Sp?6)n)>ivvWO2;ekrfe@@1ASF)5y=k-iLrFE%^R#ieEI>LD zjIydK6;>MXURu~GbsQ8^UCRv+dUYF}jzz!h;JPN)15bl-)|K zT3T8!V`H<&#>SM}9eRo|Kt?U>5`D)o(LgS`U9+$ZjA7S@kw_#IKnAxqyJn9tBj=mY z?f}T6xCgt5`e^5YSQBDxhYIqw(z6i#PRFl3zCnaq#3a4nk1>Uf-KytAOq+%cXPFVl za~1gU6Bw{tU4YrecDd&x>`6d}^ zw!uZazOww>1~%jm8bAk^tXB~*zPUk!*TPt$#Gp?*1;;(qfDy%@1}obo5TPNadl`V6%lKy+Qejd;H`Yxbj( zZ!VF-`C&6;LWL5r!9Qj9#&(pEJ32ZHMG7w@a-T;en?7v3g8C2tc$8(lwHW(-+PV}1 zMd&3(d8kjf_PY<}0Arj!aUw~tK}A`a*l1D6hOX+i(B-?qn5u#8`=FMYshy6S{r*9k zuvux*6q`9S5Ri3*VEU31t15N{oJ*_vj~zav*>r^*7fU;syEkc&KVZnfYsau>E6re=&a|@ z_dx~KWof*6<@;{CuW$YYO$r0s4kVZjlE4V)E$?sjhXb}Grl2H@7Sv!GdAuhtY%G;h za_EiBh?o|h1^@h+1UC%WIFyl4<4zwg|qQ;{ZV zz$Y6ouim@I-;Y4$xAhg7sdH5vkuL^5LvHl!mU!Hs1P z6lI+iLbUUgkO9J$@5Z<~p)E{ZE>kmEaeO$^Oixo2BB_jw8)k%!V&5M3L0>HJx2C6O zIjYlSrpvCi1(15j0pBug@GO;zaKxf;ko7AGD*{ZV1~^3P%1b~wVE_KxTN9h(=?QwU zDpGdaJqlz$k`^0#6zCqewlGdi3FPs*;pF55_qOqcUOqt}Y*h?wgD858b%k${%6=ZW z;ZjUvb-U6c3Y}lBNnAk?jdP2B`)|2s>*v3NYC6)A(aQejMIx-%SAq8a&#%KR=lAy` z>`Lf``a>G4N50clP^74|f$73%HOI?B)l}bn4YVz{q~n$4LBf`9S3-EWKun|F_~sYh zUSPR+!lozsCKNi*Y5|l}g=BFn&QReHa~b)fyqB{gz6E-8^arFbT)=o6t}td$0ZIY6 z32}yGzG!_$;WI>}WVEWRu-cG3@DCxaD})$-0>vffv*MVepMMoS8N-j#G{}ECNqh^X z1@u5jDFi=5e}LG^DWV%zdgMdi(stTylX$?M#b+X?6v#CTgfDv32BfgAn_G!RV{|I4 z%La==YoHNg3LB5d6~Nk3b#Ew+k%S3wo+J9QXMyji2nN2AVVPs%#$wRni};3fr5`N{ z$4h$c+uuH96Zlj;0DqvBGcqzp0RaKgqUKKlDG$Ntt*m%3Ru{`%Mrk844kgPMR{-CS zUQ$E+9}fph478+R!r*kp4}EbB4UJovf?d0IWyz{TF`b&FE7VYM)@HEUR}acm*>DCy zKf>Gq_F(bjy}b4Y5$5O2s{7UwwpJ6A=PfKPdkLHUbU(`t8kUk(@Fk&QbtEPSY=?1v z8n1{uG}ig%cI{-IfC237r7rEXoB5lY%M>GM5lTFr(24AT-JFJ=o}PMupHMtL0iQhq zs=gCCo?AAsHnXuj*tO!m4Jj*_>Mb<_?e(T9L7qOTC7gMQG3w>ZQ3F0k9A*bi*NCY8 zwE=Sji6$=puW)1)m2(I;X}(zUx1RY(5X{OMdQlCu>cX#piT zA_{64EszSR^y8NE(GQhd%W#|S%Z#zFz<4iDQ|&-#b`Kjwq{6uevjUcm(F8(nvmE0l zcuy3k!PTb1DljWnL~0g)K-#!AD!-KpeUm0149x1XL6VY_i~Tmd;84U(Vv%jPC_A@w z$0p}uD0zK&bd&_b69)?yDzc04T)E-I3TTq#E;E7&sH8#)*3b~=u-{li;}@kl*0Mv% zMI}-=M~nb&S%`W8*Kryuj5Tru2pdI3MRoM`Gf)*UGxXMLb9K}eRzD87uK36w$d!k% zk2654gZh*D)itDr?CyXu8*N zj|j8R>To1D4}gv|*pM&~ItB&?P$brXiX=EkbfeCXHroK?hwz9Z{$b)3&$c!xtljMU zihlvrUKF~o6hpWOX>UJrVdhaikTmizRY@;|)*NMSkA}iTvf$zOWqAXEi1djZ3!C9bY zjroyAZO~kKWqpT)^sGPpN z+qI9o$@_(kN^TMt0_E4=4sg#z7};woD}UDQDs&!J22Z9~XwgUnS(mbVbRb7no5y(@y48`B0!0~Ss>siHT0glI z$Z-P~461AiP9=zW&fP=zwQ9^IS2w8;Y-IoA3b!d7c&lF2! zo!~vE=7)d&)Q`|Dm$?Pc!IEtj?48kuV4{$Rus$nfPq4So)z#FzZO|FO@fgLjr_Y{| zI^d%hLka7(DB$br=~+NessKhiK~34gb-?4th6%n)QP3-0IA@n>^i3Tl*Q0k^lN35( z2F^BQtr6U=wcjE$HAP)i`u6Qxw6rTObs5y;0bf||#FV9}Ui6S&g3sKO4Gk4I?85)4 zs|zdZwV(ljUlleqY-}HO&ZtBOA~?U6Jyio3FW{L0N?V`_udK^5d= z`^d;hR#};TYHI3I+7*?EvzeVs@9XLWA&3GTAT4yQh32__Y;MNF90_0?C>tek`eQ0# zqlobhN;)XQ1H@s7K$H%2VGlSDie^-;O1#t}>-Gio93=@(b4}fhxujYj%8S+0i-2HK z>{bo3F)Tu8g?nO6qH8;hkQs1RKSJg030iUdRcka7dS>UwjlY0R7JCOb^`W`xPfDf~V!uf@}b*PE$sq%JDZF&e}ik_R>I8lS@BM_cXLqbrw4^s~Ykssr= z)NOg_=+SIB-?cGtRuCb+6Ay+^8qZ>T@0XoNWhRpG`>$i3SyVfJe3VU@u-l{WASgyM z8n;%(ccDg@_BB7*zH+vXD{seQx^;WndI(Z;9@sK_DPU5IU4;4NJ&GL%I~D?%VCk!H z*nt4ggvTeih>LRo4-Bo4Z zIsxg@dxua0G_F8L>ImVdtsg9O9^B#^p2!b$Uu3Xkb z5PEn?=f8^){&k=1s)B#AuBz8v^&PBSJ#IN$BAT~c9q&1~-m|@Z(%sV8#nu5QE-Ec5 zA$-!t)z#5OPE73nzrG;q;A|~+BtWJC2HEX+#l!_c_GzKNbOev*JP0Co8gu!gf#!rD^L0a1S@mPKC$ZdPvA2HB3q zlFE}EQTEj0>*1EW5#(s{qx`)vvEUH+{U%oLn>uP62ENYHr{m6$;k;nL+WTtRA=pVX;g^3;FZU6LMBct zT24S#*2KcXf+hFP$g0V+d7RjdG8X)88m^)(HTQGJfN*NnmIWzS`#zMPei zFnIg+ZAMmB+qdB3=#(%mEy)^T;o&I_(en0V4bgj8Sa2`#eX{PCbGf#Sn4UFA)GS8x zxlP`V-kJ?@+kyIGB)?C0zebR)2kcUCw9i{cQ0N%cIAS z?ckEG0^8SJh4(X$iCdXDuWxT}3yO$jQ~C=10@!|Ktnj5)<=T66cDXfq@O_n3to!-1 z?Iw4ueV>)JXZxL(a>brqSZ*cvYYKAfnb*gnuOIf0jU3?;sXD^$r?j%Uo-OCit8N`K zEYYCMHJCZ__h6LIY7|R#jCsEpyM_+}bkK)jcIGEiH2Wy>e}B?Nu$U zaNhc8dE>q8qM;!nA!n|=i3?z2wVVF+!8G40IL3Qcw*Ia7SYBOK8|&n{t@xzd@tZeq z#_dsDw~ijO-_uvMggHFjm{&F1m00#7sX{E`$cZ-$kwj7eckA2F{A~02M|W=DPJ3}* z%XkV`DX3_=Y8}z0jt)@hJ3K#f5O(qQ?S#R>!QqjS-1bmzNiZyn9wpkLYI2 zz7sM!3kwSza;|A|?$c?{pYPkbbEoX)>FTG_lmbHUy9Sy@%lu*O3GD8@hNg~ceEfS| zsaWd|OH7gPr`>FSSVW9YpFi;!@#kRNcQkIMyU5tvVX8fwY{7r#jNrL*AHJ1;4rJ}v zTwfyRn3pkTe~`85B^$5$m0uwiWOzLAxl|@!avC{v3aO4~WaY~G7{DZ7whyT`bSyuB zAPn$}{IMTm2VrnxMk05xEA`{uC@u?2Zk{5@O?rBGt4OxW&3!j=lkJ}&h9Hcm;Q}<; z{^QF*DP@V>e}!|px4kC25*BxAhd=%#5{G&3yqGk^KdFdiXro8Y{AT-Sn7Y>@jtVD{ z>RTBZ8F1_dr_Un@sagOrYk4Q@5*itqL7C~cUmkCsY>E$nkC(gbbJNvBxJt)jyd}IA z?{dmGDo4w?={Y;+m6w;lGnaD2?CifQBraD7unALh@Y!1QtI3Ad-a^(}2n8e$bvRfMGN*09zSU#zJH&XWbEZnJT-i3zU5iJU*S z7H^FBh3Veu)O9&naEJ0tt(QxSF7C10RJ-lx$IKj3_udd+zb5BdYFOUAYf~R7$svt< zXJ%#=8Wxt!#OL%WgDazrWx_FHxED8vAvi0>5^H^Q_!Z)5xcNSW!>v zrv@xBBf}unSMR&joI6gpSTtJJ=hEBSbjdze>RhaC;~Xt#i?*sjnjIA?YLB5b?hy}} zi0V+%`M53YyR^Y1>AnqR|Jr89lWH)!)VDh@0FZ~D5ruiA6W zg$M+Kp@Bh7eZA)1Bf>hcUGNZm7?-gI@~208M}~$HcON=4{`+G98Z#Tq6E0-r_uO1= zOG}I0-2Ex(D}QF2Vx2drrS1{g=1jiEdS*lUKYw0hrYxlQKbAVRbm4JL>alz3`pZwe zvAt~x0b6b+CM9PyBakGQzFDB(VRy`;o^?bR_E$GE|vAxYP99k=OUy2p+k+p}j+26<6z zB>?Z&^&H>Jc=YJev@RCJ1r$N_!ViUHx6R;Y_}irT;XIWn;2qt zsH>3dpo?>FXYspc%@X_4IF&N#)Tms7$Dbt-!k>j$c)Hhi5KL2RXiIxb3SBz@tPFI` z@L_xwI+4a_jkQ@@4kz6+yHq2P7I~`y0R{DNg?$z)Uyjm51QN z{|Hw91;TI)mtX6g^Nz`SS1#8$HaJ!%@(|Hs-GNB#Hqx@FD5Y!paS)jd)Q4eEVikBy z$*){EsH&FkH(nX>|7>7rSPQ43(-J}K{=pctYkr6IE`nA zkmkswJmK`I_gB6OUklX;8eQ^8(e~6{DV8_IS%{Fl2jnwkj7Nc2V3yV!s&DD(>l>Pw zq-#b=37k2j79St~q(KZ9HP0w0kZ_yrF_HI}HE?uv3}{Ii_nexXLp_cU%;e5~ ztOzML>*2#3HcB>f*jA=ZEHUvLyU$pasMqDH+FMo>X%@a68kro4Usfg97pz!YSy?QM zwYRqFe-Gi#U2@)yq@6lPTXi|CkgUwd_-Q#}_-=_8UZyO|zR-RCj-1Qd!^KrDqwT)W!Ij(9 z)yjwOQELY3_yFwa7#MAU9+UgJOWo{A9Z#P=y?X6h*10+0#;Kn^UAo_0s9Cl4Rg9xR z3(?g0Ime|(vmRVoy^&&X@WX6&kKN!d#4&9wmeAM9hd7>QoojctZGI3j|{3fdLHoCj-W`6L`IQ$>A zj+tH2Udu+)7f1L%}JP~ryB-H7Ai9f;X$ zksF0Iu+33Y_gf&o4|8x#P7^1;@Rz6JdpJd;bHlqT<~a@D3Awmq>JR>7_?@YUqh@>d zjnsz^cVLK_nVCJky^LQB;QB-`;s++14aHxu?hM zerKL)Z>d`=x-+saqh{`0kaa;iNZk&TtalCx#|E{tTR8IEV}_)*xUf(%I`YTAo?d_C z?-b{yNRQ-Te0<8kJwKNC=FL&Jxju7IQBmXQR7It<7ympfd41hyx_>S>uPo|pBvi?k zWu4*q;}4yk-HN6Eeoz+`q+0TrqE9hpx-$_DH!3LpjjGC9M;HmMd$S4==5AR>G*6#v z2o7*kGvAN=-j60tW@a+*0ZGsKo7NEwNbw#}cBcWy&Ye5gAj*K~X!Pv-Z)I)}@~7#p zVvm=3{j~D-)=}TEcpz5G^;6ux`sdu$32wV8bnoL`+bOBEgzc&lEZ_GfL!SiY{w;CM zQ-|h=nW=%eqX%;c3TqF1E9n{)(_Cbg(!vPpGd{RSrW*z1`?*_s*amNn)Cv|lFdzh_xbyz zsYH>}tWWaf0A6j=tm~HwKDRCdzTo!Ru?0Z?6B6k z8n63BP6bPb8n?aszTSkDPJ2`ql`y7>%Ni)p8okgEPm|Q^_kC|3y}=~i?kKhQ9X%qN z_&x3HjMqB1T!C}qRt3*-_l)rxfoL&Na(opoZM!LqTVdyi@%h~&$<~5|#;U{TZ69t1 zs$C`GwJUD)6E>3t8^Ua9G+*uh&Gp#Hqh7Dgdd&DRz3OTc0CP3@iA6X+n}V*L9{LN- zW;5$s{UgnVVVk(!x_hOidmZhIecyhUnlaiKtV%c6F~+p~DXrMHknN2kwnP8+WvrMt z7WN~MN`%*p-!M2=tM7yCIPiCN*fG1=_<`evt|*J|lS^T1X8u{TlVPXSf-_Cc@c zMTg2l+|Mo=4;c`bKGP~qEYpQ)&wETs1~p&GLd)b;cJ`mptw}ntNZL7B6NtS+yt?;U zTf7IW+a!CE3ZeHTW>1uRuAJI3F(@c#u|?c%$ef|At12<$htOR^gAC0gEkVT?vCO=y z$?MkBf#+4Y$~7ud`?7!JEy;yZg0+%;6RQ_K8_c^E%B}3x8+-Eyi87Z4QbQ2sVxS58 zDsW8$q}U%BX>FZ6vP6TKDbWCGO{%u`&R#;``M&L>1;&+wkxMeH<`ly6=c4{PLRzpB zuG*<@VcMBA(GF{?nx0Xf0N;`uyKQnLo9E`cphm6l$>>5jb%&cRIUgMpy7TUMVB)uu zl7asV-vXUzmT!`8Wef6TvWt|7>QdX*6xlLfRG02RI_}nmi!3fLx20%C4bRTzG&Sj1 zM;P#<^Uuz`kTA>R;N&h)&+#{W(!uuu_pV;K@{+ftv@`?s9jbZs?K6VJ1GUeJ%aVa! zdp~y>y7^9*9fj!DRPDMv;gQi%JGf2hOksCUCIEcOAP0N~IXC#2I0`e9eHGr>qYJC6 z#AuVG=YL=R?>hYNA^3kD48ukp$F6E<7+P5L?I%@V1ly}EVP_`` za&2&6;FPv@qp3DF711#@&4^L(o6>9c=X=P>CoS+J#DMx#EM8Unz^M?-~o~Y%IHNfLb zS-38wQD@8Mh^;x-KU|`%U}?!=LdKIHnYcrFx0YgQZG&Hf!XhIl-$!zEzZJLUC2xE0 zKtxDJIz_`D(MXv(9dA+*(2M^nBAu?tB_ z83`F>HHi_{HCCoOTPsn!a*EVp;WF4RV^l$}d>_3M+*4RW{XiDZyC&h=3n7HGxHx47 z#(l-p4OIyVmvA^YG1R7}MBxR;k*F{r4N1P6L#c=!tO_MJO0;9&XS@#_KR z0^x7prdQFn=1ePnO5|L}Phy;%oSMb_7WS@8k~PxP)AKs-5tCq4RMToJtb~H$k(#U# zG5PDm9n`h^^!fAQ0|(-*V||TU9yyE(<(A*ZHo}g96y(KRy?V9f`7!a(*RK;h^R4Zd zM(bfT@`H~do%f_xraI<`Pjlc=dDNaa`O`759XXN$iR&;sy9NJ=C@2IM-J_R?YSc+JbU)R;uo$SbsReNzFeXf!^YZ}N73I>?>RSc#% zmbPh4!u6UG+4k>`i?G0>PF?o7t(sRnVG$9jo12^8M9Bgi!idib*%<6CVs5TOc8Zv= zu)+1~Zz?w?h3em&Q(?U@@4vA+m+MQV*v|D;;5Qe(+gIR}l$5}VR|i+%sYu`g3Qd#Np@txnJ$tBb#>0T%zdWdZtX$p7!xa3TU)w5$z#p}P0vOB zeq~nmk;&-T)&6vpmw9jzr=05*NYxvYnYpgCt<|Z4K<=ECLIjz#UY+fQS?U4X$gJQ# zbSUukGMYGCx${*n(A^J!|ga;*wc-NJK=$5cFnFdV5k5 zud14w;K`HK+kF{^nFUZ)LRDd3UmqTJ3N12G$CN66w2;Z9Z&P5CVAvmgY1LNB{_^FE zeZ~PqM;aEiV%YDjh=}H`TelV|lpJ?ve_M`eHf1mtzQOVd=%y=7f&RnNhx z=(F~0snE7nt*F;M$^t*ZNA(8lg)%bx>w^k0G&VMuRcUjcST|3h7{P$qb}Or^9q2yZ z{76srPSuVL&&|y(uc!cTIO(vEQJbBKlBCtoqoAR$L68%Zmc|1pyV7SFQt*`KdAZjIQmk2Fx49#kBQUn(p1ZNePLGhanyS15J)g$>GENELw|LgB2eNYKa=My3 zO48nlG=-eedY48d9(?rhp-o$wF30)1S44_ROQ~~J*xkE#KMM{vguC98xs zKObi)jvP&atRm;Nm;?qTHgjUibw?Z!XGk-Nt!9VRq?M6B8o%QFNnSAxs?1%?`-4Mp z{)m52M^vR9P#J5@k{-KJc@)`hy%RVb+1*3{D@NAH5Ij$(1Bfc~_vZDar=VSm%t zRs`#_@F*c6f!AE-{7b0uwzU~RCDtg)50(?nLAc@pMoi1{L~Cy83xMP?J90)CAS3`x zGJ!_zf6>1m@pmf3^=4FfuL9~-0uJXw*<*N`cp^oYzIwDiisZFq#e7`q8c_o35max$ zP3qw>+QLr%2$vG0as)98n(ZyqAfk@bop1YmHzrcGa%!A7E+9S5bs|4%Yn!_rs?0@@ z@}&lOIauedv}#opd)srdxv%-PuWs~z-exC(2iSh!j}A%8g?;yy_r{n4tZqV%sM(~kwRHb&TBAV}Bo>BqDcN|=FL+a*J z{+Om{kG^!HY*X8zZ^6vwib%Cis#bIhBrx!`1?uwJGL6Nu%}QE2EoJx3_(vV2D;cyi0=66b<^=?I9Q(`D&?b_G;_DyjY(RxV|=C$i=kF4+7 zKp-CS8_A~mG?0O<5i!CmUI5T>$ahA7M4vu=DzNX!`PL(hAUX2Ee#dXRx)xM!Z`g~N z7F@}`QPd7N5gHSd1AJhMQdC9KUj53BwSl^!oa1kQNR!Kpbz)O!0935@W%9@R=uJ#a zM9R5k@J@gq7b#&&MBTjaT;A8J*6STOyz>#Ho~;+*93IqU5)cr;Ph}UuGr&&)e#H)A zsWbIB6iR?i2^kw3qwFo#XR+2Y;@HunHcH9+4;@kgsPR{k7{mE9`!QE*Lq62^-B{K& zG71kDHc2R(EzLAqGEWye*^AI2%mb;tNI*b9wArg6iOB>0t9{YqrYj5F>+M&r?QnHHv2 zwd=i8sNrm{l2T_Zd<^mQF=JrxcR}n%zdKMI+hF{qIFfsBv4Z*>`Htr z#xEd%$+xP{pg6`)?S|#7J_lq%67Y~Z1=$T!`E^-YSulp3Zd<-+zR6B!aj((a$=a9X zUI8cIDh88oh!hi1#x-2?%JjqSN3$hkTo}EJ7ytBIE$b)SZG+2iA#U}v7{>ta!a3-4 zxPHH%AgqncN z3qvMI#^Jn~@87>~U%G2)X#zYnU$`z0nh>m^Ox7ufUrw_$372%}yI>EC5N>JGzBp2s zO?Aoe`v8yHFRVtMR;=QE z!d8HXB zBW9gYVatM+pc`Y2u^#RM5eBhaE{RYG0-eAi>zo9Y2|)}VfI`x`;e?@)k%jYyVW!bU zy>!2Ut!+Apr;(|t8)I&Y>%*@%)`mjDqM|Z`k4pn1a|AzazG-coXjBBI>7`t7)b4J15g7kgqz zV>){(t~N|=)0fg|jj~XvNSpx`fRfut1#gOBL?;lC8Q_abwDm?l3{V>)@6H`N#sL%M zoQI!q`7Z0Cpdj7r`kFG^o7oN9omZDHtO2>T)F^U3!o7ZyeQ9vf3j~_pxoWpmuH}(DdKYAgfQ!E$Yl!o&--n{g1y_cLyrp#X{!hmlZDi0FUXcdU$`hYHdw?a1)_AF{ zuhC8>NPPCc-rrg=S>Zz|3P48_v4zj=B7+r zSE%%&elMzOp$luKGhZDPrXH*yAdx$H-8k!dJoJr8T}np$H-0oUv`^($g9g z7N;YzGdUimFdh^xYUo z^EdfA=-=FojH~*oT4W-h2FiAU`>B7EU`<(HfhL!g@`US5OPrJ4pgrIQd<09=4tWL#vx0~)nlf6`cLjI*`}G2wSCX&; zb$NE%4LG~Vd(zdgQxJYvfl6mmwt>eah*fRs5r@adQj3dad>3o^DJmk+l}F^oVzH=U zV`5@L(Ru*9*b=bS2p)B#k+!K#EnqL(JKI-r1Ei=iv@G=W^tg^UodWW&1>}#^_icFi zZpHkky{O_BZ@iF*<{TKQ6wu9Wd0ZF7Fkq-Myc2O@E*1zST=_cW&kvNjeg~QrcE;#?kU5iBnI%HUm4;|zp0L8!aw}*V^leCfsgU(CrH;>TuP=_E8U$^v zVh8P#(anscRcR}282|x69TsI}|3ZiU9FW#qV9U9>+p@IUXwz@bI1n<6`tWsqyLE_Y zE2+159GsqPlqUCijUA3~0eRl-LCme7m%bZ~_?#h}<1T zFJh9HWYm3#n>!aRC&wyPbz!HJD%%Gj3@1DDQ+X${i~3q1Bxho`3aA5sCV!cjY;54+ z#40(=iF(fez6jtw0Sy#nxP}DJWlG+Kq{YHDQ&5kAm^X5FFGLdwnvEhAeM|E-T;8bd zMJg*RQ3q>AJL7edG1k|RiRFY25Hc_XSEBki)tZ}|I|^dzL|UQ4ZLVT9CR_}Q5^OYj zLCAxV(hl5%4WM~@i(2>jbE46dZEqMRPeCFPca~k@V z4)1qWczci<0>Jh#eSh=Mt<%;2*?9o(r;8VZAAM_$8iAF*)JZha>*=*f219FwE5kjj zf5$%$|JAga(Q)73^{suWsQbe~@M%ZW8s|3Ub|S2-tZox6s^CN1i8g-ttrgIsQXRSZ z24qm%#wGXk7wmLb^ZKO%Q!>H0*5ZsukPanQ))2eK#*#=mCXhFdTSJXdUHTs?Ov^Nc Y5BJ=e>8(-_d>6r}YF*B`bo0Ug0n5w0VgLXD diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-PiecewiseChebyshev-1.png b/public/images/api/qiskit/dev/qiskit-circuit-library-PiecewiseChebyshev-1.png index 0d58f105fb7b6cff6ca615d68d5213cf8da2eed2..fdec8a478be70252bb5e671e12823c942e22da40 100644 GIT binary patch delta 43 zcmca&eZ_i$n}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5ScO-6tn}UU&k&Z$}Nl8JmmA-y%Vo5ScO-6tn}WHXiH<@>Nl8JmmA-y%Vo5s delta 43 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 z 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 diff --git a/public/images/api/qiskit/dev/qiskit-circuit-library-XOR-1.png b/public/images/api/qiskit/dev/qiskit-circuit-library-XOR-1.png index e70f7278a80dfb864391b582d3318f9fc445a5bb..71fc51fd37ed1f47f7692d1f3cb40f93f187916f 100644 GIT binary patch delta 43 zcmaDH|2Tevn}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5RPY`MV diff --git a/public/images/api/qiskit/dev/qiskit-pulse-library-SymbolicPulse-1.png b/public/images/api/qiskit/dev/qiskit-pulse-library-SymbolicPulse-1.png index 1f953c5f9f646369e561c7290c9885d2ac57b3d0..8e4672474371f5c26300ee86ea5b75b4f011a2d5 100644 GIT binary patch delta 43 ycmeB-?2Me?reL9Gq@$2gQc_TCrLUixSW=LaUy_rVq?ccmuCMU>-;s@J$~pj24iJg} delta 43 ycmeB-?2Me?reLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*OpvJL=BBo9ph diff --git a/public/images/api/qiskit/dev/qiskit-quantum_info-Statevector-1.png b/public/images/api/qiskit/dev/qiskit-quantum_info-Statevector-1.png index 81dbadd2ea4b073f710f86c933bf717596156faf..eafeedb5d3970f606c09119be800a6887e2a983b 100644 GIT binary patch delta 43 ycmZp(ZnK`?reL9Gq@$2gQc_TCrLUixSW=LaUy_rVq?ccmuCMU>-;s@J3bFu4VGuR| delta 43 ycmZp(ZnK`?reLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*Opf-C?(cMkag diff --git a/public/images/api/qiskit/dev/qiskit-transpiler-passes-DynamicalDecoupling-1_00.png b/public/images/api/qiskit/dev/qiskit-transpiler-passes-DynamicalDecoupling-1_00.png index 3d9d414b77e9442cd8c282713d28da3b9a732a42..e70e82bbfdd0a4c4bde6fcda411a4d92dce63a6a 100644 GIT binary patch delta 45 zcmbQdiE;8K#tCi;7J5cH3K=CO1;tkS`nicE1v&X8Ihjd%`92#tCi;7J5cH3K=CO1;tkS`nicE1v&X8Ihjd%`92#tCi;=6WVN3K=CO1;tkS`nicE1v&X8Ihjd%`921^{(` B5dHuF diff --git a/public/images/api/qiskit/dev/qiskit-transpiler-passes-FilterOpNodes-1.png b/public/images/api/qiskit/dev/qiskit-transpiler-passes-FilterOpNodes-1.png index cfac40a39a0221f10e955c72852d3e8756ad14e1..1571e1681d2be6c0700bc26248e8a8dd43f5a842 100644 GIT binary patch delta 43 zcmaFL^OR?Tn}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo52#tCi;7J5cH3K=CO1;tkS`nicE1v&X8Ihjd%`92#tCi;=6WVN3K=CO1;tkS`nicE1v&X8Ihjd%`921^{(` B5dHuF diff --git a/public/images/api/qiskit/dev/qiskit-transpiler-passes-RemoveBarriers-1.png b/public/images/api/qiskit/dev/qiskit-transpiler-passes-RemoveBarriers-1.png index 4a1389a8db7b55f9d5c75507e4ec711557d980df..0671c9835a984579c6553d5d7d09d853fa11a0fe 100644 GIT binary patch delta 43 zcmdnVvy*3nn}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5-;s@J8ax0$91r;b delta 43 ycmeB^?30|}reLmTqN9*eQc_TCrLUixSW=LaUy_rVq?ccmt}oVXac*Op1`hx?G7h`| diff --git a/public/images/api/qiskit/dev/qiskit-visualization-plot_bloch_multivector-1.png b/public/images/api/qiskit/dev/qiskit-visualization-plot_bloch_multivector-1.png index 716ad102ca7929c36e95c642094b2707588a642f..abda4e49032a3b2d7ebbafa74d361153b3df6074 100644 GIT binary patch literal 92847 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

x%Ipmxd>qTSn{1$Q(2+~ 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 P;D;LQnNpR4b;SPzJwuk1 literal 92847 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%0D`9ls3*Bw=6t!?oD&76fw>N8xbUGM_~ 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 Fe*l=4Bx?Ww diff --git a/public/images/api/qiskit/dev/qiskit-visualization-plot_bloch_multivector-2.png b/public/images/api/qiskit/dev/qiskit-visualization-plot_bloch_multivector-2.png index 7d1bedbec92eda580d6b3758d819ebfc7e03b67a..be62559f955a4d615455a5d382a3078d64ece875 100644 GIT binary patch delta 20104 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 delta 20104 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 jTW;_MZk&1pj$_C>F*eBo E0L8r$7ytkO diff --git a/public/images/api/qiskit/dev/qiskit-visualization-plot_bloch_vector-2.png b/public/images/api/qiskit/dev/qiskit-visualization-plot_bloch_vector-2.png index 77314955f0f0c2caa86c2ee6ee9b601642e4b9a3..ee6c12d917dd65e2f2486cdd4cf44ee9262cc515 100644 GIT binary patch delta 48 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 literal 10055 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 delta 43 ycmbPIJEeAln}WHXiH<@>Nl8JmmA-y%Vo5 delta 45 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�oL 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 literal 48739 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%0D1L|8>#6GJUdMt~ zyAnF1_?m4znEtQw;UqcYtA-CtARc!Od0gE@8g?!nRJJGx07$jl&A<8Pp9vOO>zg-P zyvWDN>0Vef;I*`XGtNP(!KPUw)PHT#KgY<`*2u^#b#-;+Q740%_{qu1Nm3cBE`~9f zLRM^6tDB!1x;g^WgqD|=3J3FbQf-4sv7l!TU-U4gtCS^Swg=lv^R=3W3I=USfJa0O zIF$Gox92Astv(VT>a|j@{~C`Cqt!lZX%{6YIiXBZ-?a^gMx*s!6O-=_K^e=%~ zV+E-BcnA~=(4dz^;d%08R*$dQw3u7iig7CzALGqmn5>GFaR-41HA=m&POX#-(d$9w zkKUI@FRIJSwxgpRj_SXxWsrzeg~j*K9b4ew*N6>d;F&%!Gp@$^dc}$yc{-y+ez~Xa zmCn1j%`qKFF}MTz9J?$EGzjV(NB~414vM%|*h*Z{$X4XU4LAuRX}viaLL>crW>3C$ z?Tm<_`F{T!{>f)w%~lAkpP)FVM_I1p)r19r^p#kCv1Bh4O1OId?Cf|EmpFehO7BYK zr#eothTMr|jx5tRXGDEjbh^FL8Xp9UY(56mN3QkY0dthqvL0COfgT1RTfmT%qY&}< zG22s}ZU@!xd}bRv0RKi^Amw+^+>OQVhQ;@gO(^~RtM`s$DBv-SUP89_K=crw^aO`0d4-_zO*xMYAi`vB?7ULh7#fu zW$UADGgpcMr+?v9+zrNzcgIi8rwmH*0AJ2}_4Y}VY^UqUdS!v#nLF>|*G;%KFBiEs zoka=G0T|jTGXio)_xSOhEn*@Jokl!iZmb!>!BOh&?%S*T(smEm587bZH=woW{0bYO z93X^y`W^3oU8?(Fu^j7G30f#EO^$f0@e~_EwS^NKLzC2cE~jUCiAs|_p_$lP;@v7q z(TB)0xdEHDlQGvKYFYo9-B9XozJ|BQ4=q2_I^7tQgs z@4-ARwW5vNc>rM&yBl_6@neJvA1#_ar{Z>yHDDua@CthZWB}O{p!8r!%hg}vAF35f z-Py2vA+x@bE~uC-kKz7)@rtbyOADC%UyO!Fx3=s#YJ9)RmG;(+8#Iw z3p1|-xt=~vYR~y{esoWy0_q1WU$)F+sMti*QBDX2f~vIgOFy$^3z;s@@!P!Um&tNw z%UPs?GdSBvLVd!#WUrao8jMlBFe}+By~mB_zyC#5i79u_)V2)KAA?B3!@A9ik}Q#R5P@?zYr)hRQ3LmQuZRAM3*3ztydMDGuT5pQ+-jcJds zZ>5DC6;`9zgZf|czm!XuAqd9w&j-fLRc7~KQpX!c25px5y83V1R-J0snfr|SHv^^u z!-8gmB%ENxjX45v>B#L3VF{WgiJ&teUBZbkyA>_#ub}>fa$}cx(DrYi26Pa6~gtxc7kAa;hZJ&OOQ>V z0`@syZaUL8dqV!&&Lxi0ua9j)UyM)8zvQ84qsK*qht}%tuS+Ozy_0UaG`cK?=hY1A zY`)MhkQB*O;)(ddn#~yQl+fF_6%b%Z*r!#+OHO7HfyuNAFo3Pnv&0`Tro8jsVLSZ7 z`}gk?!3z4Ah;#lS4U&6HaU=Z*Y&UCEnlz_m+)x z<0810G_ilAas`>EMTd)5 z^cTLldv^KpTz)m4QV_w*8cWJ#m-(ZBfH3vm*@|#GZo0e2zjz}*<$vBLue$Iv8Qq$K}emykD2Pj@C;+Mi&KC|%h&YBMKs6%s-wDqhh;Qc_TjyWt%w3m^t7xjB_i9Qyp09LfK7sN!L?+cnVDJM=1wiM8Mrc^kT4IWcrr~=Fp-+w-C)cAMVy0WXv2RYF^@W)8>8EuV*l^pz*_Q zO*Bv7hq>D26*qSn;trROn~<=+xWdt-GogEvJ}Lt`Gon#~EJD%ZwU6DICB9pd{=3l@ zL%N|`m@I>%Q|pc(G8|!fu%OUY^DI*c%k#G*G`V`@k8_u!0w%90HDR3sH95Qg3@~B} z<2okwkK{C-k#2$BS^RjX6>(!i{U+y)EjfGOX26ZT>$+4;3Y1x*^i0B!oLxA(aEtMa zcZeTKIS>1eju+3L(-C2D+j%x{U_Ob_OJY+Dtdm6Ss$-G-Fr~*xMYc*} zI1hG`&lpg+BirP19ehZ%aZFe4GqZGRZ)?$9oCj_SJW(`HZ$&Wo9jzZ$_hn-l6YQRK zxOl|^Sq3%BoA@MB;plfUctH7-cdDZiB<&6ci!oZ^pO0z=NIBbZxWW$Q(7zB?XGxKG z8k@t_-+Tv$ji51fy;xGc%hGDT{h?NL$8Ay&1SAL#)h`uMd zUI%z1flP56%GH2|!E5#roAc_yiH;m-o z&0kioznVpXQ7gV?4MH9k9V)}iPW!4I_Be=3Yj=U>6nBBV8?T2ihzcLO=R< z%82fhS#k?H9h^t9+t4sVh&41cG<(CHp>NT&YEF|2Z@yo zMh+&E;?&ERFWYdQ;C3>O3<8ZjD}srf0cQvMYa2!#$boUmmNox80InDqaw=RT|_&Jx4J!nLYyVX+Y-}|Cr9aJ+2Aag0y4>X_O3iL(f46yxK0cW5aOyt4RrSG*irRh(WBRP_hGjj z>}CL2lIji}($v%Y9#!F8<<=CF^S=ZK>!0l%FK}iJ&~D#2V^rAYyehZo=#u4S$48Kw zIG7pm30NZLs|NCs1n@xJRqT75f>f#>z%U;$%ExLX8D1MyaFG*ykTBIzGvN`E7{*|< zxsbC4$4}UQlkaZ9{T5)Jst`v_7D@`DqRw0Eqb^`dhFGs|E*Fo+)Jeql1@4cdX!`V=$d=T?gcb0Z^T|(C(m{)oK!7^Uab^ z&M`Y#Jlr=u=-&rYF`roNV6loC2nu+W8@+RJvO02H@9f#NFh<{iD+t!K!dAPybKCOI zZF~Oq?GfXInoGOL>4`R}r&WRwZOj8JwUclC&;4JoMtH-JK=nA3>^+Q5LpVr$hEq7I z=b_GS*WHhqCByW6XwfI)K_lD-h=t{zP#ds);zbgaR6mFw;Q@nblrd)`!}E!?6}^sS z`iE*PcYZLi-ospg;Z}y84Eij@9p>g*Ozde2c11g)?Kzu zw*enBV?ThWkrz@o>7_bwI#hmmYMRZO1fV{t*RLy#Z4cka7Q6+YwlD1f$Tt zI1M%2M5b!NSulI{?=Op*N(vJb-LG7AWI$Js8o&VD8n`du{h~4w_w3IW#91P+igido z#3WOy?7siW)tH@7c@6r^bz#N&1h)q$-{kNgGX6jYou}D+&`uC5HAT*%*)89Nv$V)T zJoJ=~;^2p+2s@cudC15?j9vc#{(^1gTQje2s#8{~a*rblX{)06*;u=fC``tSe8-^V=mo(ab& zQbx%r*(5C~qdu}4AC;t%BynsRQBj&kN*gUQvIvvuM z|Mxogb$_q#_fwy9-tX6VJ|F98GWP-cOjIDB;*8trwxjXoA1I=7|zU1L?4jH%C0*Y6TvN)Q}MWKs&~)W@jsqs(Hv`pnz9-jTvcw@i*h&9~+YG z_(VbX=$@*JJ+p;k`O=tgtCR=u7Qe51hRz+1)5GuOv9->#VBeH&|PUeU;#lX}};+PQ@c z^3^?F7VDme5AmKyiQ-g_0!WOiqY-2Weg-Pj(fS+1Q>sTFB;-_RL@}p}{j`2WS;@UH zpO)am-yZ~<#sC5iNZuq=sYQskAh}53;YJR6ActW3{|^;T=B-=e037QBJ^OT1=ku-z5@1%sD;gLO5P%c>vCF&R z;6tyu;$0gSOj<{*JQIlAv-44HeHHuLcUG@meMq28QP#{}6olSjUK}PfIK*_4yZwu!} z#c90uUc%ltJE{WkJ8r2Ma@^f$F%~@}WqVNC83b+FiwmeUwa|rzp}^=e(`82spiVO7 zlK+WJRVb-`W=@w%F3jq;Urf{Uda<v&+qSCLk1C#Uj*e;{6J2GoFg z2ZX*jURjs_mihB%q=pV#0n$LZL|dUFM&4?n6RmPa6W=#wHrH1Fx!JHp(Pd!05McPq zm80Ee$4pCbT!(tdY_p5A=8tL%Yk(n?s5t-BJDYtxBvrEM6_cY{sK5zY1O+&5E=7ky z9k*`ZZ7g$$hhRk1W7`zjJq?Sz=y)Za?b8D2^0if1ObFVlr%x+*&){A^j2_9{MQ`m_ zXOUs|E6Z;zlZ#C9j`Qg(1svS@%lfbjJ^j4xg8w? z(oKw&hPu)^5*KWRN{)2@nwpw*j~`ncIADx63;>J6`t^J;T87Cs&ej*V>1{=iZVDO1nc?vbQid% z3G-q5o$H}~NR+7St%qVh>iO^md? zU;+I!K=aRs8{onE%U01DrKGMII-u5jaOH(Y(wZ?CUMV|gsl=mc`S7d1J((Pvf4E%I z8cQ|a^z>w1u=_L^l+M<;jGNLDc=gVmJAbB~%+AhE@i@#sDk_R{0Vkc&xg+^^y^0`z zQ-&e_yxFBcbsL;>f60^8rDx4zf^Th@Nw~zUn>Y314mNdkSj;w^y2FzZx`8w8Nz!n@ z%p+zG1j#PCv}$JSx7b7w9FM%i-}=^|uKJuNcJaK>183hmtv?#Rjac{^immzV$(l$@ zW#e|!-P^SSs`&8-{`a&}^8|*JG|$z3>UE0S%DRx{NlWo|2kS&qMd96GLd@E6xyHzVHInI~d_(ZlJ_(9#kxZ+;R7 z13NKqZr{Eg79E|iz?HKka6$tL=TsJZq}EmLv9CT16_>k}SM|np1?^{HIo1#OnM?H8 zjpo<@de^XUUOqN`ZDktF->jhfryu`|W@R>pEdIWee$VrBQ{Rw3(RCyI7r;wjphyM2 zyNAo$7!_&D{W%a`^SA}~mU|Y8gzZ{i_)la^OrXBLZ-rLgWL%L^c;kgv5V|hy_?WQT zeATMr()k|&j-$Z;A0Y>Ev^a5rG;M!`WIm*yN3h+X71WS@S z=*_xdKIXS}#n<|juF%%{!^$!wLj~4@5#WZ1q0mQS}Mb4qW5$u zJXq2u3`{<14*`HR!+A5AWGccpUDu>t%$Drl(cNBP5uBA7^-_n}a)mJ5I* z4eDgT(rbWeF5GtAwz}gb(R30sd9%~K^Fy_E)i#1W)yyylI>YS;yA?)qr73kID#tD-4{1uSY?|m-ddiScz z`<1;ig(X75wSGQ#?}rv1?P7wQM$u@4KoH$~DRCOZ>Fm;xG*F;k%DP?U9cvv~0=b?t zl=`!HB&*siT4hj(Go^3{5%(qBA!hX=*_EHT|0~7COl`f$!e2Qv6#7c)s z6d>#$$&)8CXes4bi?E^EhrvD4mKxr&NljlXCdXHMw%%LP>1SVFgrLi92vntpG74Fr%{+ea=h}S_ubVUs07l&@{e(k#$io-UD*Jq%(}$b`&ZPM! z5ps|b_3Rhrzw7XVhPO_%7X%iBh@(TsY;|#E?*EGo9IADld&2!%0D>RT<~{DWD5~CX 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

3^Efz`Y>xLVL5cM0W8yjVkr_L?IyLWo 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 Z90SR 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 uL}$iM6MD>yz)us8>V5{AB2+ieP&{b!RnY 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 a(w1J)cqO?_dmk}s7`t{RnwpKN$NvGZ21IfI literal 159837 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

*zEAz3c`=QBW7_t7 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

@%uSP2OU-@8%6 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 diff --git a/public/images/api/qiskit/dev/qiskit-visualization-plot_state_hinton-1.png b/public/images/api/qiskit/dev/qiskit-visualization-plot_state_hinton-1.png index 94ddac67da5e8c726f98d955005c2a6afa76ac40..69d0934339dc05d45a24a3b3a0f7ab1502a6ae26 100644 GIT binary patch delta 43 zcmaD8_9kqCn}UU&k&Z$}Nl8JmmA-y%Vo58 delta 43 ycmaD8_9kqCn}WHXiH<@>Nl8JmmA-y%Vo56Zx8PP diff --git a/public/images/api/qiskit/dev/qiskit-visualization-plot_state_paulivec-1.png b/public/images/api/qiskit/dev/qiskit-visualization-plot_state_paulivec-1.png index fdff63d9c68a184f00db7c57803fb5cca1e64540..7fcff6d7838ee3c93060ec5f7304aab0ad28244d 100644 GIT binary patch delta 45 zcmdnl&bYIkae|wIg`Sa)LPkkRL9vy-er{q(K~8>2PG*u`eo?x delta 45 zcmdnl&bYIkae|wIxt@uRLPkkRL9vy-er{q(K~8>2PG*u`eo?x2PG*u`eo?x2PG*u`eo?xbO}+T6`-k7)Cg-dltJ`>4PPydk8 zXIgfL^uw4XYf9Ps;PM;3V_!)$yw~?@<4ej;EKvtW?7Iq33yit9Y{#wh^jJB&tn-iP zaT3&CfTh6ClW_wFoIfw=sc;C6UwQvLtMlhqPef5Cj$i3;;FACORmjDfKQAKvQOMSy zP&N7|+5i0N2Ces>d$Cje&#hof{%5a{xcI*XL*z%{S43-@n~E|r?;1iGlV)a&>2Kat z*X))I*gg(OaaLUN$f>gFxRBb>*46R)uy^kgt_%Ab&$g#1ML5Wh^CL0p9sCA$I(2<* zO>TL(QnAY2B}cuadCqnacbNiNMCdI6B{J_|Ha0ftc#o|Qfz4i67)?_CW}u0FypyDpVY-^yK>`tEid^YmmT*S_4L6$|Wy zdweD}1UB)4JLU#3P_M6K$O?z@Rqwd*!r2ENE;IK5P zO2un0(-_X8n5)4Pd*7*fOx%jP!U$QZO#X$M1eKlLT}A-`tt7FaZg{hPLEpxZ)5vUA zUX|RVM=#~%mJa;M|Hw0{2liHDD0fVo;y^JmdZeyG#ouV25GQBjF} z{^A8a8m`EcPYe96I5gH{;~yCCt9}mmw-yHnM>gwm=JUxpJC}CR|K|O4mJPWS z<^3}f=Y-h=S^9#QV8gyjU{}~+C?2kd!$&VpibF3x!@bwF>YSe02?w~*K4Hi$O64X` ztlvr4m386V#QDqnnTYseQ?PVu?Hq@t+VD;3Mkle<=5Gp)#TNI-(>Yz-r;+m*{JtD0 z*B?8X7DdvcqKRjTdvNEB#LiMfKIUa~-11Tq>%je>JynHs$a>6*=F{_Fg*SvyCnR=nPj)Cr2H%zr&?~ComnZnwL@Akrzx5{OFWDTi5&Zx*6Z~2 z^gnlw`bZ7ed2Ge+*0!q8lNmRpiui2ZbfQkad(pu!B|JK|Wtk|JfgSY?&rnkZ*9Rm=!KeP=-?d%E({u-H{O zmU2(0n0TC!!`d`nM`O1{&uOWGgxkpD6~N;OqfX$GOJAa)VXI{?bllI;@zblp&WQ{`T$LU^*8gk}51iVv~pK=gs&hIY|ryfmh#Emn=(?RoxnhPi+vI zRM<35r<+04AqFF*B+8McRFBJDq_`O;{u4p`$fCA5pH)xz4B>2OitEG?iZ{*{Nv-1+^I& z8Ry!PUU9m=Plk0eva&W8u2TzoYP>j2*q$KtBF17^%q~XzRRoc2RzuN7LqnfhzEzfq zgT}8{>JhVFPA`TjzsoD8`9A;N>PFduHpVKtp^8W53ehraaa3TeV|q&kcbCzy`kH{N z`0gn=rDmFuPbV6Ev*dER_eL8}E{=q&nL}009eQRVv4M8SKNWti5}==AniLg_nu2p|IP>P={xUN&vjnZEzjd*T5%yxuj?4Z` zh}$dXntEkDWiN-O=`zyYQ>Xf)%CrM&GaKt0)oF&YFQ-!TI&PX|(V@lc3b?Gl+!x0z zdU6r@F%@Hmhd#-O*%oZdEyPcF+)}=2TcM!S8?#?2v70d;qWz=0kn|=;~)LA5|mve8$&$cDDa(Io6X?l=?N)TJWD9u>zr8J#RKJBRRIQ`J0 zUfA{Ns9V3o!6$0$UDY-c+6{${+|(|G(9j`4=3Ae#F+Jut)IFc&2NG*tb@IK7j;BtZWZ>toY^_=xI8y2C8nrfVj^XJqGK;`Hal&D_aywJE z);H?DQ!cgZOk$S6vQ;%U)wC;=zUAcLhfM2`m;us>xm8Ac=q?EUuH%W zX=6`mi8d_7hkY939Fna}tSelkMel7yD7seac|~|)=SEU}-0o&9ik-{vOQt#F&%AZM z>P$faG0CMlzU9w)UMJa`mZ?%I?50md7tjyL;iGxyR-JVzuPX4`i zQMpr)V~+@%|J3*6eZI_g13#xkca*oPIdAxQQtNNNEc|CakvQYmD=I5V$jH)o?52!I zsyv#v3JdR~Bq!f1>FDSnAtp|K{aR3f?yh;SjCzUIz}~GCi3rCJ{NrKk^#l=?T+x|M zL*2p2zhXkB_aoNIQ`a@5G&*y{jqTzMEz}cnlOCv+5m9g`-2U_=v8qJbEaBH+2qsNb z-Y1OJOq@SLuD?eb!ZUV&C++C0x21_|o@t5egLWF48IJ>TGOK4O@2pEQQwPuI`c%)b z4s1`nuTo8Su^v~6UNwZ;5YhuRp?x*pPi;4tjJ~|sU(`tPdm>_!t@GygpejpmnNU|_ zuL0X%7s_OLm8%t9PMuP#aLN)ut7ix}3=q#1Y(GjBy>%$lQe3J`1CN)oU;II-<$Gbe zf_yb~V{1$Gau{70A(K14+;E@9;_yyULvI%Ir(Xf_w@;!=P0TKJG2ipDzZb$))DNsQ7-eTP~STC)e-pu2HH6mSqS=WS3>PoYUi zXlQ719KRdy{>f9PW+#4zu;$%&SxbKY{CVzd40b=h`n%E2$|$erK`CCtUgOH4p6DxG za>^=a4AFEMUq}x9*a9h>4oK@{bBXUjrm@aR}G5Rm8Tlm30QW2=QZ%ys1WiBC}kG`Qc9-1 z3JI&4vSW$nd3ZBuAxxK?H^ffPq*1UlvqdYEE@zhm(DB0@yUugEj6VJrM!Je(Qb{WN z4B-=~LGO|#8C6{JATiXqF639*=6uimuMeF4Wp-(&&r>htS1aYH0g>Z%UP&mh0LsN$ zpr0!mazk=sCMn1i{yzr0HNdqzpBFZ1#QdGpmpaI9Vy?IKsa zMv`vOR3y+SHFbT6x!iC+I%~u+yM3@{sl7X8nQ1@rXI@s{_FG+q4RV(@5g(E zJT8qqTo$0r4if!t+>&agSn%D0cc+m9yA!`U$6+7tj%_(=ubrAqDXkamd{#)`AFNh! zM2ds5%wBuuvi4NcA;^f6AZZ0lxWe$}%^PuX@phj?>m%%TmU&-(6ua(oQWmvjoD-)3 znlvXHBa}r&>lA6K6A~Vv(dZ}+gST%fEvaaexUvR9GA~?kAL_BCS8H)bFFR3v#E@j( z8wg*P?ieaKO6(LkXG-bmSAf-V43F~Id0tn%nDt7JmsG+dSV4z)W|y93c0|xaeZq}Y z_Q=rzJ8y({Hdn@+>zLr(b$BS9WmG%f;}Ns6vNF$hI{dn~P$KFEl(`e930i~cC5SIx zOmrG{5px=}c}1rwkFxtx7jR{>O^k+d@l|}N(^{zM%a<8WLn_z|N53n!RLXPj#v_?d zg)w*AX=Q~yySXu(8>WVFESHMsNz2#eQY=@b=`w9=oNGU(Pl>&AL`7LPScxkaYD&4O zg##WgIF^&%Qn9WL8c3I=EyW!D?hLJS zw#PR*;dUV?{ruRTMZR$9qtWb;>Lj|ic;bd5G4 zl#Y?_p7h--jmLYpbb~MQ=Cx5iTym8$jYqG$=m$3r_xaa0Zxc7)LiBmfq5>h0nZvnK z^o5$5OGak>Ijp0pPQ`{I5sUp>oTQ4laLsSEuHyJ&%*jDIXS_?d-qTPf4^F*b;| zgHPtfbf5p2`vKvgmZ+$27d;4=r&n7xyJMQJH!o5X1~Jol`#@AcBppl`v#?XNg<$YyBqe`;g zwla2ru{u_ATc8(myES|c>9e0O1cP*7&~SfV)k$b4I-{a_8ddYCyx;(lVAe0X z2>EkXI9!w>o<*ZduHjfd6}v&xfP|t`0d2OO_;hIH8b8K_Cm$isuW}lkmvZoRWt=`7&Ofi#kMj-F`xFz={pxAe| z<24f?rE3N-FH&V+ ziQ5FT4B%6h7M&OfH*Vf3@BB2b=X%Yi=sB}eM_pON%O^m_VZinV|vd3iA<+#bLI3lw(iYo1DgNYkuQJhABTZ;qJ=F$=p^5WueeZod0V_f(mRd?_FRG=;eClj0U%s-h?#z>BbPCIn zOqPI~Y;fUJBi*E-QD&|8x!`2OZN9X3EB$JB9NvYcoIqKg6`tJDSYAD=!}s{f6Ms25 zIsK9W5*nI3la5p%WoUl4twPKljfXz%?n$RnPGqvxFQ^}@(bj){u}4?sGwg9kg(l!_ zTb$%brlH@y{Yr$v-m2hum%+@f-MusDU~?_4w{8c*AeBF|WXQ8r;i76b8Rp~j zE6KEm;ipgxr%A-8)irS~aesLWT?Ze5*JG~`Vp_Axm#d;OdF_evNyz^}(t`f$7i$vE z>ecznK6v1rDixdgS+AZ6j-Jy{!*%pQq~EuzaGkX_$vK^Cxa7pw!IbdTEj^&PXPwYx z;8NI{V25lklp@N$<11!@YEE(IebTAYMKFKqhaso_G+E{a9D?7ZUtjF{62dP_Y29Y| z;=E6yPqKTfpIu{?d5kL1f#0K?E?>0m{yVHa3cxe^<3!acVp4E%2%6VFV^ApNRGYA? z7C+C*cs^^I17{yhlxM(}-ZHhY$=Sp;>1--$`1t!1WJw@@LIn|1Q(Hm}B^rE=JT3~Q z!(mv1{EIq9>p!pl`&ixX*{rA~dRp4rxl72>YiNC5y@E5&J;AB-=TZI*lmB0WzhMF9 z&hg#FZ_#AoKUnRna4Fz*TDny}l>6=5qshrh#_QLGbai!=B9Q8UdhiCZvBt*74aj}N z*|c+i{CJF(%hRgt{G==F$9zl#67CV58kIxGYCElEAtEH%VELZ8eNlZp&q-${e zS)uNb*MI#VZi$Vj$J8$h{)3g;xBmVLA2s`d|QL|Lo<6MWls01pPqX;>~KONMm30NB_Lvww(7E)mqm zm8~r$4UL$oUmub@_P2NjI@;SqgM)3`dQ#HT5W9xUtov3V2U4C<4DZc-b;*^;o{fDr z>9|p3-Y1usm`KTMpAMe#9o?@deSCZXJ0$l;65mBfXAx2HrknNTg374uZ$J+mM7kY~S z2Z8@z(jhg@(c@CPpQ-qx{( z<1J_CD?Rm7cw%~*nVw#R-*v;!A`Py zwY4RQ<**({52{22HGUn`9WE|zXk46@@d!`|&Eom)9A-g5L3D7FVMkwqk;BUGFHbZ6 z+%)(#s!rJ1&5fCrRmyJaS6h|Ge$1kYiHSHG&DiNR)0&8P_N>hMRFlL0Vo8C_pAJXQ zm%lZRsH5*%$U)MPP*P?>qA@|M>GF*yNE_v@MSt=U72fXdu3EnSn_~06k7;qP;=!Ts z-|LFZB2V*s^=oZy4l7R2Gm3xh+mQB+02zXPY2P04$~%QmN^DnjyuYDWk>1u=SFYy$ z9PR4i6qeh!SA+9@Ha2$TRUeu@Rs3_2`7gk^%QvNryR%in4rzctL;okYvs0nStf%=O zI0skZM>nN1%BLE`^KuXf14MOZs}^*EHqMebhPE1ui#0VO0HvW(QKk-m4ltB~@6-P=@rF8u2KaT_d zN6BT%z{8^oMo)g9`9EsuBm&<8(cD%_)6KC4B?DoRk?Bz2=;`PfZr%Fzx07aQL#U~{ zdj&yl>)K=^2?Yfsdaf%gg7U7pvCZG=srlgZiR=GV)7;8FMnLc2AV?T}LqjHRZsj7= zE~dgfsaRf-D#OjWE+|{=k+=1Jv7Sdx&HGXS=nEzWhU4BCz>c~mGHL-8Ac#wc@8yuC zGBC;Zjt>0AfhrHT#A3+kEQ7{yUYoH;Hlb&b3m?3xBOpINy11BAT6(YP1E<*j)}mc; zT1pBdJ^lBTWk~zYsc0)EM#hZN#$&ilc=VU|>NPUluwsh=)4@_3%KMJlyp9X$&|i-5 zWUJcw=zE?f_uab-_?dq$pSTW}-@bhtlKnlb2eu|vGCDOmnQn8TucOZh@JFr0GWIkf zrM_+ovLNUwXXE_Cax5>Tzj1@NS_@;JfwWec6f++OOU2x~PD4YpI9MjXTz%we6Mp>2 z58goQkt~RRD{^mRc6`utE+dVYgd~Mb%lXUK%;OtdTb*RLzDQ1QDgoK1E3Kw;V>KF%c#)+4_ZSb7F zsQBE!=eCvYd4zS!YOLYPr|{KP(LBi~0iA!MtM_yqC~D|$ON|ndr&*uzmoLSyV}iGK zR@&en^LyyHgE@5k1H}HtQ|_nV&VsOE^@BUt-1E7w6Z2J*T?u*jQUKTAFNDnc^Ok=; zvBE%#PkKuxNi+azcp8AjeEiWtS{MD77tms8Ff1V1D==!IHj1B^(1)ro^X%C(m?-GL zZja=_WCN*7MNG_95izkw!vd3^!SvtlE;87Jv#6&o4V7o96`2BXfn8+Z2i5gDcDKb# z$=<%u-QB$tDySc|8MMrR4unC=OtIKpwa8*X>85mCDBWUTLE4X1tAf5e=DqBf^DfYT zpRAkvURB?3eis@0=*vsT!t8@RPj~NUy)MxBVNlLmw@rROtqY>b>&{Wn(kQdVJ9n^ugj#9jOFdxExQBk2f!F$&U#4@v@`Vfu5(!qs#H}~WrFeaetMwN zt%Tb7Hx6hpW_EU&wzf9c=~$;<7(NXgm~pYh?rqKuSC%8Dkyjb~X&MtlUasfmcT`?HP zMYWljh%1c`WOMbir9Nt57#$dKd3=Edp5u)qf(~4>Ir%A_K4!X|g)Uj0`JblaoBRZ1l zD!8YtlSO7-KpN8CHk;^ATR z9l^eHmv5x2mslc$Z9aG;8<4~%hX=dOdJ_{9GjOIof`_Z;yK>ZfG9_>{G*r@zAzLYV zY?G^Y!6O9}MS5Q#y)-7wQl;ZrVQwwLWVe$%RqdbIh=zu5GoQW7`5CAoTLK*IlxRqFyFWy}oD3Kno59*0^8qNTLIPXKI z)jD!?=rrWHzsPGl@mkAs*8uz+VHomQ+uG_zvJt>|4nnDThRORY>#ZN#CDqs_m-Eh$ z(}ns!FI9rq?L*qnNgy0@Q(6h8{SbS3aPsSkY>hHG*l`xy*pinoPfqs$m&;Tu$^_pj z8ys!syLXH4H9k7G)qH<>rl?1&qrzn!8jZ5XM``h%Oi+qpcp-q2OI+BOpzREe`|tMY z0PbO#r%yjRF80Gv1KsB0fHE@TXJ^4u$6@)>FQ6+z%N70M!-u)fj1a&G;!Br~WgP(4 z+8SnU_p-09aqlNxgz`dyD13e@!lG9A7+@-7$kK?^U*xQg4hHOcMsVg*7FR}Vn>`-b z6!e*!4q=L>nq!&KuB+e4x+>kA2x$Zc`_ce}!N2N6lpoMv4`}H2S9?|4t+wNX|DOyD zckK?H%GlTKR)pPdfo((P;x|3^-7hRIF893P!6%iu7t(?h_EH=oBoP>01O@$s$A~4xPffHfuk8r_5rO#W{$XwTOUA) zR4cU}6)_@Y54R~|;cL5XTG%gI|RBLEr_7o1v`YioGCqBV=7zMM^4gy+n;nqqmB^_BSMC zM~mQ5HhA`?Fy*NBN#|MedeAv{*bcwXw!hC?3>1gaVb>bjSRv}H*w)^MLO1H|n>Vsq zN;z+n_?#oNvu}C8zKRTQ$%e*z?xEXh1TUQEp@m7yyo$BAkbBX7zHCSHU#nLEE2?q@ z{0%e$n5nV^1O(o~L?leP-2uZ+L_{P59dbk2Jq~~V63HgTb~TMjz}R;J^2nvxw0I?R z^X$W|l4_G0ZycnM-gpw30G?v`pfrA@!ME2JG1GBw3YD%7v3xFaNUuy%(xKUV76^@K z5Ood|p8HlpAnQUwKujD+DuHvR8Aw4)OoxW?IynUeg;lK!;wK?mwY{*4!S-7Vs^I<^ z!(Jdb19(P{zQS!8YJYe}{Z;MgU@p{scMlK6BvHc6r6G0b@goTVqo_GZ8-j&JlE!1> zed8{Y$WT6Jpnl)Vm3VZ{hF(uGc>Qi5%n1}S8T^-ZCdn$s5J4vE}S2FwpK1<-Fwmk$^@(10HS<$OKdkmg!$+P=lw(${=GMS;gmo zM#6h%ccDn&JgVCP|aw_<5>t#`C*%?@}ZhHbp^J%E4(o6c*;vsX+x$aMrot zw?l3xK=={w7mXjO?wq{g{0>}_{?~8b+=iVB`0?Y%!=TiYzdF;TX_6p4ee?42bV~*T zU=b94q%5{eEiEnFhpRzezM#Jj*YpC35o!nF-0zaq^J0f_5 zW%&7VYu<~x$qnZA#({0HgB^8|m{|W?T^%KOMa=e9%Gw@X44Rlio3U?io|f{4(kXK& z5!SLpqM99mpT)RFKH|Bb(^hCAPkZlP@5=TzH=LhE#mZOwI@oQ^JwkH!gdcXAOKm+X z=4AU?eITEW;(_mymkhgRAs=<}^l3`4c<#n|9lAu+OSHt^?=kMnPmu*eT?(SE1b3jsTEGnJ7Zr@XNunMcXwDBk?6y%yyw_phOm|N7 zMM_H3lP6D-17>gn!?psMKvvuJk>PHwPMPH&VZr(N^uOVm){Ng$&3^=Qg<$sGp4ULhdt*tGv3;!z`j3`uGEtsUxRSBa2f&g8<4Pd_rH~=b#BF-snyqYHE;j1Cb zl8pnf6lH<2xNa@D2nSA2PNs-ayF9Y0SoNiLU-@#y_6e+)5HY8%FKc`5rXX1cqJfc# zNt}@Kjtp?e&AKaAkAuM_0b-N_?nqh1Qaz1VDEOEVd~|5L>1IVFo!|+<)+jP=dwAup zc`HnOb$-?pLj!n(n%|9vrt}hD^H(4Iu2jh@Fr$cU1|>A+I5;_D_b*?*tO(HL0ULvi zd_#EK*Hbw$0QW;orvk$!1&9F1JyU3wMpO>NWO}A2b`KmPd1K>rAf@zZS5PbppcEgL z)E;c+c`3qsVg~LzEp-C9PXn@ms2-@xdwcVFY_3%Zh{5T}mDx@r<@5ehsj%SD!Me!) zd6=h{h+yr4WW5&MbOQ{@*^V>`n2&4s`M?1%hIjtFvbFUmUm~hZaJD4l_*7+OWtr5A zv!U|c1mv@gLuev^C)w zOv2kE!&X)!Rs9%;EYF?MGyK?%jx`W5;A(TZZJDFnVMYyMTp&NBf(xBjpE@iLYkKT$ zw1L}n$7+~waj0AwG0D$8L<|7Qs5@vHuY=FwteTmirZb(Ehmq^jeqqgo(p)DqW4 z8^mY((@gU5S!938-rjQhSTLV^IFsO)b*9+oLg-UO{I`+N!5ax)ZcYF zc2VD_dU_5AJ2sFp(%=_%&$J~?PAYDQ#n-+%KVLjxi5x5P$>0H}LnzL*Ccc1L0h|>1 z{36RCwMw_`Zumq1hwJ<+H7Cd_Q}e3!#34F5+EXOBJofA*L7D+3_P|uv#%7Q9JZQ2` z&@4$XWyzz>2^SDja6FP0#1qeUx+wLKYCPo1$leI}SOvxf%-DvGA zGl*~3-_Oo$EEKfxZfnmiYxB}Hy!7>D;^Nv2M!pL`rVDse@(HX+S|+B3m9;ev5LZ@w z8?C~1kSgXAlaoCAzvB1@5F7=?LQu=@zp!AAAZsLeYT$LP!t6dpus^Js%q6h1v-7X* z604D6=dC^?&3(|EX| zOd|gIbKLQ8b<5j;s9tTn{Uugb1OW9iZV-F^z;7cwVbGBqN?eQu%*v(7fCkG(wL}6Vv%l9}HSj)eaCh1n4?oy&C-kg(i9%OG5)Giyw^QY+Ptqx3;~I zuZ;x27L%2MVXHy;2Zta?l|XJQ4Gi4Y1gL%W(V^S>X(WfF;stW3^Vg2y(2apApr?W0Vn#OYo~htN2(t~!ji zs%pbH%x{1`G}~I}a~<^|+vqcj&j8gz#&0Dg^b9axb>gzu*RNk=w2zjfXvuJ29a&bl zD#^%LH!TZ8Cpl9g<0J5S8BL6R8{ir=hF_WqXu&&?Z!LitQ_@<+VbGwlZgZqAyDTYd zK{gzLe}wI+K2+2vSA=c;t3@7^2y}4`3=D=|=WFU47^qg&Kx1X;E#eS!lTuN!pjivh zU~?w}OG3H}&@bzN>0u2mJ=n?X&7j6RQzXd1@KS_$4gr2d$0!K&i>oP$3#mg21%{F# zd5;mx=>UsG^e|Am(jNj^T3VER&YzHJ5%3K%fPgl0J*7kbjpB33ze-e3()8S!vPty%4 zMu$d}1SqPbnT)i!c961#cGFTIAZK8HRngILi?FgeA>kVT`Y%q`$uQ+Rkfw{hpOLax zpyjct7~zSiHOHmF3^+_>Fhd;sxb0_Tpt%Y|WyWAK^n-&~b+~8dvEIZj61NVN@|`X@ zVj3cI69~@3H3+dO0-^8Mtp>~=dV*RolZ9w)uv6`@RyAG}&3psCA=TE`v0dT<8GvA;QY4=7{!Q*s8$2C^^6ea=2k<}_)i!e^h zx!{q_BGw>O-`JohxiEu}WqC8H!%IcC{z>LijDjq0k~yk8&UCJpW(ZQeZ0p literal 15394 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 LNxJCngJ=H%PiUeO diff --git a/public/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-3.png b/public/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-3.png index 14ec5dd1e12a0d550358a64ea7cc91f97edc28b1..7c30efc59979e61928cc98aad0b81f71a7e40e1b 100644 GIT binary patch literal 26603 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

{4AL@I3iEO_6EwbK?Bc6|l9YFb(_B(nC~ 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 OgT04;&D?YH_kRJa3m^;t diff --git a/public/images/api/qiskit/dev/transpiler-10.png b/public/images/api/qiskit/dev/transpiler-10.png index d4a8c308c4df29c70908e033866e21e44cd50175..f70da85b3003015d8c234d889f0bd5ea9ed73038 100644 GIT binary patch delta 43 zcmdmQvEO2Xn}UU&k&Z$}Nl8JmmA-y%Vo5Nl8JmmA-y%Vo5Ckmr4Sqd diff --git a/public/images/api/qiskit/dev/transpiler-11.png b/public/images/api/qiskit/dev/transpiler-11.png index 711224a5ca61d5535279509bef34e72b14ce6446..a6c524d2fc7ffb6394dc89ee287b1021ec8fc4c5 100644 GIT binary patch delta 45 zcmdlri)q&^rU`Be7J5cH3K=CO1;tkS`nicE1v&X8Ihjd%`9$2 diff --git a/public/images/api/qiskit/dev/transpiler-12.png b/public/images/api/qiskit/dev/transpiler-12.png index a0895424ee9a35f7e1f0886ebc9b233c345def0c..bea05c03f7210317135d814dc75b84da0e0ef8f7 100644 GIT binary patch delta 43 zcmdntw!>|Ln}UU&k&Z$}Nl8JmmA-y%Vo5|Ln}WHXiH<@>Nl8JmmA-y%Vo5$2 diff --git a/public/images/api/qiskit/dev/transpiler-14.png b/public/images/api/qiskit/dev/transpiler-14.png index acf918b4920c2b0b34126231b5e3a80c3d1a83ef..2f9400f180bf8aa9cd1eadfd096c051e7342da33 100644 GIT binary patch delta 45 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

6PxXHVAC_VT(VODaiXnNFb5AUe|bxjMqx6 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 literal 24728 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 diff --git a/public/images/api/qiskit/dev/transpiler-17.png b/public/images/api/qiskit/dev/transpiler-17.png index 0742a68aed073ec3d1cbf82cdb2a5bf7a15449c2..68c343e9a2cda50fb78ce8088eed345d0bed362e 100644 GIT binary patch literal 18832 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 z´H5#ItzOjKVSGz1Ibe~AaL;iaoLf26^`m;A61Ig46*1bxLnQnxEe328tRQcRz;|WG@o2DnS9)5 zP*ancAAMXN%{4l+n=gyOzAy z8A_jAU}%~fOV@ue(mfW(fcqY`$%rlvGKg6FMKCA0Z1S0^l=Kee)VbyD(M6Cb|BG1w zV~Xp^&ezFy+n$PUoWJKR9<6E1kU1T!;kf&xeBsmVDY9(l!1~JxK7Z8@ZM+gD zkH3u0_&1&V;oB);(LFDb;b!bmRBl-ro_U;AQ-K~YsA7VW@m%J|k4h5_p_&!W3$YmB z$eg~!k4gg_(!U8O>{OKpZ*8g%^3RIOU315--TKUdWvAtz5~0V(D+!OYQKz5~t{@RS zE%BrD<@fJO+uPgMgoMf(EARM|QM}=I-+1IS^ZgchII@FQkm;NJPC#V+Im$~1drpmG z=d9h#qA<+=D7%YU6HO}JpK?BuR@>7O{&MiyAY<&usgpLzkOMJ!n18GT%VeA@6@Tn*yBh`tt$&vOHuzzj zJHSqN!=j6YS>qIJ=#}5&_~#ds8txQCR4&}HdTjQzqf^D0+Rr|}!|DFSZ7c1Sr;O%< zQZMsOVwFoy=gMLShF61be?D)%u9qV)rtcwoa^@%9v*q%C>wlo$&L0B*ccT+_lmt?BwDb!oea2~BgYaB)=yCo%Lx)Ek#PLyK-o;|o6%I3L26}q^TivxZ zphX=&I5=3@+$^ctSY1`UfB)jdC(wd|o80Y4QKi4Nj2r#0e;$GilJoG>Q^KQ=AAOt3 z0Rqpq8%_T5E76jMi2#R zGD-;%?zIu3N|T)<|1O4&{uW^IJrdvGZYY%XwZApCE%T$S1s>mjldS)KN$F?|p_6SGmWyO1A*ui2}xFB0LsBO_A|xbzv{MGpD8AP{hC{w?F1Rv#P~YM z)Xt}Exx&K2guV7k3z|_mFDB0A`279*^Z^CD?kckTj{@b*ALZf|XU(64ga*&R7toX6S{41P3x zwpg{P-<_?iNf{^!dy1)8US3`uil%_)LM{jyC0G~qJGP5$vVeXC#kLIXf>hXJX;to< zQKdOySETfv+-psML#j4}(5V+$sQW&DKGUOX)7=!w7Ff6oZr`pPj0h-&>2B+DU`vRu z-u@MHc>%0~sk+u>lCbeWPYNh^oPEEx=7{cq27!qL?5|Es9QLny)(1ZTLb|fNtW@Q; zKHmu>A_Z(v*Vx(R#KpydR(2#D?wNsh(`MKY21_Ue-a17_rU9BD5h-ml_<4j1-ykIy zXnk~a^zyVxA|v#$K7NFgK_Xfr!TYemq6nELZ1RJKkaTcPg2Ok;!^1-@Q-gz)L0k{I zqt_cLzR6?`47nT> zE5zc9^ct#Cv8uTQ$GEwFf=9(^scMszlT)F>Wl6)x=>5S)NzLrY;Xz4(Y#k{pn53bz zote4S8OzJdX9htgw&?q4XaUGP%oQfbW!N<>ie39XBt3JOPY{zeL+QmLA|ut4_n#6H z7n-%xgM&Kr_9me~4tR!V-ucsafMi`{HOP;o$IT&!P=1@?M>YjcIE|k!Bc5}eX`#+b z!`TqG5i1(fJP$AL!osi{jzer~^ck(N^l9ZN*50$NZiDk{o|cAD$@0m>lVfydUE zKQ?)Hsiwx>``Mtf>_6$r#@qU3IGqV(8IDdZftYZV6OGIgWrsrZ>YH9|wed^@NAAY3g z3!%nLaqiqqh{)orR@2M~Psx)cwZ?b+NUp=MPIE7$r^WMJzH%iPo|{>n&_%h#8uI{Z z%Jpp^Byz)YH_6g2`1;CtZ>>{NQ?D2DKPmbvECRaJrNNT+6U4;4)rSYWY}VwZZ^1B3 zd-kf_$C`M4tGCM8I(+{8BVN1Nb#{-(J`-MHVQG9V!@bCu-8{m1T#s;~r{!*7-U^(wrTk9AjV55<%Uv(iB z3_r3Bp$wWbG6CTkPb+jQoU;*{STf?JOBpzovB1m2gGizvqkI5Rv@xr#t&P|^VMIXj zf5BF( z1i_)$YLFG;1dK{2Vn`m+(9wAt#fi!Ikt7vUZBTk$?(GdUY^rwg-FfvvdJ$*2!|itO zF7W>C7PiI+WGci7gYuoH82Iv~vaxY8ztw=TOsg$ddU|?>YFY@)x>GO4#k@I+gQ+-< z&ob)s=g(jzt~oOZ<7fWky<|XeFa*Qy3%|q;_f|9XtIDmbw@s_I#slj&f(Uc!K}mwO z#|D$J_%^yMs(pWc{*kMjTT^p$vv_N7uO<`<&htO|@ZIy~>|ZdL%!={s_U9X?df|oR zJ+!SunnGL$qQ?^wQ}$KRM^E;fC8+;7f>GqQZjo(JqYv)OjcxCP)r9VHCrgNBL-YA| z&)fmoM}~#HlcIP1BAyL#1ni|{^zQT5AuWK7K-$1_Jrb4)lZ1o>x&uUTCd|(5#Z#T2?13gD|vxp(uOHDZHrBZLKEit$HlJnaH!y(qo7E!=+2nk z-yA7vXIs>{S?(xSTZC%L^xWNeE8$%Y!_Hf^IqaUHQ9#)Ws{-qR4g3 z2_7nQ40m#-9BQOO>6_ZxdH`}?gc4Fqi=5c@WH_vgu6Bt-y|LY=mH^gj7f2wIgClK} zVkx_7el{(k2MXMUrmeI{QOJ9%jv*o}>=GI=sX_eA0w-JDJQfCXB3NK;E;H9+wj(7V zD5y|T;_-6g*B}~10kMG0ff(dz`7Dwv7R#HxF6h%sOyqj+XD-$pdKG~YF}LQR{Ot|% z_W~mx1&zgE6#+{&6c#T+`c!K=_~ew5k}~_`IQ{p%?bTet)F?*J7+Q#Jebb5{;DUov{n4W=dbgQN9D1cn=LM|0da`xp2PKAHgKZS4d6Loz7pgU5 zny0-W)fYYfZG>D0YYdsb{DOk+RQdDT*>_QGUnq+gWn!RRgKNXpXMMs|mA_%$!3Y~q20%d% zmPr<|B_keqte05m!A1`m+M*{*JFmnwN4wx2WC~hd(;&3_^Yh;zPOgIrhKqM!%uAR? zZj_Ro+z8oa^;c^_Nj7YG7|{%gy)p8)yk;SkoO&Og9VeGzJ^0tUW_??4qzscD=sDhu zZ0-Ux#cqfPeI|8vb={?Q4}L|j=KvbRBsXhR!j=Q76&W;hCwYXt;^^QuJUMDdyQktpQ4dE z0k}@er=oOOA9C4V0nHE-=J4zF^#=%ef_8QHcQ?75%bFXer&dkCEaEiZcb!hqwszR` z@L*rqdH%I^)w;&2%Q5Te7@O)m3BuWY_<|*@u3nGkhNaL6Z1I)!#$q2f?K1lmD4R9i zpwu;&*tG1)N=Hnt0FpXpJJa~?*ZS~u2L+7H&g0uooR{#b6n2_RMyiyw*NvVR+l=J& z8hB%%(TdbhicdNap%@&%7tu|vt?J;C1N6gTV`BqgNe*JZ%fp1IsHo5|FeSf%lc#u$8S-Ivfv3CorR^e>bor4)P#J~wJ03)VhR;U^QC>*esDjzGWrpkrY8|9H(4@1=jIsFDkAtbdR zAp;WWZ0!?*jbWYWIAJFl$TFQEMQEh&p6Z3e97>ZO8U?2EuCA{AX%LKc;Yl^+D8@K3cMV`w8@(`y;Uy)TeBO&Sz!#AE6!^LjJQmC#p-(Ql>{ExDwZ&(a z@I7fgUeGSiYxLj&Da_;*R@SD+a4;kebH@69G=ss;t^||V`~1>|IP2lc{+WTIOaxr* z+KD{s<9-0RT62g$^xfAY)hhHt%kwksv;>Fqz8rg3FE08~c)k9{*sbBd} zbffRVJ+N4vrlx-AIM?+Ju=$-ZD}^^a^(Ri8;O5jTz5gp`jA(OL>Of!o9svOXskgUx z5}YIY3J-`|p3$%44odJo=%*I6O+=bFMnpsl=Ou0^#EZ^;H~sSBbp1iaXk`Ff86>x0 z0GQ{8hli2d9X$lh1({WTetyuaSAR{|c<<`w;j|!k|9E%jc#=#ct6ykns9mSL01c#t z4|Wjq++!lyG-<5{3a>wX`ji9$_|bznw2PU=N_Y=23#Ku8e1J;kryE${K#R-D-seTEtopKkJLnWoc}m?UcbD4ANVHx{BQY` ztjz$JL1+=SpL}r*m#di@4^onx_GZz}WVm8ip}8vLrii{@IwSr-OQc}Mh8t2-=)oz* z#b-#tfeK(}5}an>Gw-;IP)Nu^P-#e~GVsXzTx{sfZI?6)XEyJJT+lY&0SRmkFpRp_ zt;6tygj^`7vA{t*IJweWsfYGH1QevMp%F#Np`-RG62vNTq|yr_B0pqNb?{ZDDkkJW zGQ^G72M!dNg+feOobOl`0k49>&jUF40@&akSQRuIcd|4x57yEoW`UEY(R(a^I;G7F z&+CV{LQ7x3#7HZOtw#`%P$vQ&&4evZ%VYck$;vWVsK=QU=@c2(5&2Icj7yuH5)LhB zVhcUC?U7^#T?9&^yt}ag8y!JziAsz5FoC)lta~XOEdJ!xRwAEm-`pug@$R=H?IXuYN6?yQL1PO;g zuMvU;PkRx)GdOaP3WWMx8Qm`~@9n^WVk=8;&#h%c(hGu0aNF>jni|-D>kxP%ORE^X zwr(Lu0^tLSGiTn5ESBB@Dr5C>K`P`z`Z}%`w@@+?Rc{2b?+1`pMv5xJS$oAdFqgjm z{%n9jkzx1psy1zp&ql@x7B|8}ftb=2uO93!A;D&4eO(=v4<8({gh={3VCkpGQe_e( zHeCqCWSs`y`%Vyqnnp$pz>jofl^O0nIDjyh3&S=TdIdB$VJH*9tUxFOi{~{Cj_khe zA3uJ~0iObLGQsT$^?|v*yrj1RHaRd<2wO&GYhz(B?eJi;h87ZysF;{~ngSgMrd$nM z=(+10C+eyq;ynL~F&m%-0NY#y>A{%{7i2|8K>C3Cw9v6jX^IIw01(!P-IvVa7&M}j zB3i|Cg13HWnqn`o7NiU-u|KP*In?{|Eb|uR(O?M?7F^F^Km@b>VO<0)jlh(4 zLkjRWZ;s~bEw!7t0SOZU3vi>JPDKf;1n-m@?^zWVRY-7fdU_*Z5OzBg%$1L9U%pA8 za*dZ~okbBXqzB%Etp*8NB+-T?B)}j5F0SkC?G*$c6r2kO)xhu=At4Ps4L3<0H;7K> z?_ht!9VjY-VGmJ?92O5+^TvDanERVwyLQcw5tbdDpCR>Eu;-Bm)*Ho&x^@hku1tP| zPhi_^m;5X7q+*5$KT9{?O?>aiQNDxm>l&B9X!!WMFOx&hdKEiCNp zg^CrcZ6d*-nTb@AC*2F?L40oh>n*RZ*BSnVsSseKfgOIWIMrdgjRqT}D8Bv0&<%iA z@U3S=LUQga-EOIE znCzQj=7Dd}3&4md15=3iSV8-jFP7st(X4r#F|Ak8WVpy=0GOGuImkKzdiJO+Jj>0^ z_1p((-I4k^737rhv9Wis!x4rGHp5u{M}3Kd))n#$9?MUFr(9B0R1Bu&lL3tI!{A_r z>Ik&^lShLF;%NI0mK;qHJ>@CKy(88=z`sTrbHJcue5l#j6UXr=f1xEhliUF zLiETkc!}(<6oPKRQ$r463K69cS^?rLqAIunUTUta266x{FnJrmBw?|}S{*7qMkT6A_edde0E8;O+~jNvv@eaEn*`;PiP%_cec?!> zH1>`S768fYRI~wvj)KAm4P=0O+YM=8D9P>Oy$@UwwFcIcdV;v;j2_NuB#9i7Z*6#^Y!#e0j zHlW#t;T+h0h~!D{y=Mn5F$4S)#rUR#DH#>Q$hUPMGhbKjT~x@5Vkj{cAY z$fLa=Xk=bfO%*J32SwHq(qoUJ1C9BFJSuiW2+DAVI>k8}yjZ zYk=AuBF-arUdWz5p#SR-XDz@|#ndwZv|(YWOchwHjI6Axf`Y>Kh|kDtkh@J=UcWm~@O?8IW8{$T?)4$o4=I7qWif2!%0+*2kM5@7O<7?HH+Xyq5KQ zWhGzY8dRMk$dJ-I=X;l>VV!*AmpdB^nLyTOArD7G(nod(WDwy(I_QnPgTsO%VR;rL z?16HpOys#GrKE6(2>t5Po%v9?kQXn$Bic41?jWnZ>bMLrejvoO3xg$!e@hUsm(##6 z3wo5=R<#01bRg^ZAaMm*67c5@xS4)2*VU^vZ2> zF&mCoR4sodmZZmcYHMk|F1G%e0e>q4F`&Wml^$4W>l2|88Hmu;vprwX&MGRZ2Vh7U zur`Fcs+FZZ8xj!z5%HwZsQwhhDt%=2LTr|;+@Hw@JZ=d)6!=ZTeCG~;3Zz3j4H5_M zAU0M($R<lq$&mRiZLt1ehfXdzk)b! zjf{+LIQ)_`i?;ts!)Flz=pvA=H?_pp-zUb{yri`wj`=0Lq7!|r z1Vr)&&~EF#WhM>|`K8L$km5)E?*Z!xRm9>t*m5i1H#Rn&qDlG%HZs_woZ$aM{qb*D zU%Vm}(gnEb=r}Btsu3($Aj{(mS_afl!E?2~H4!ROaRJirQ4~SoJ~s`R5Rn(C*Yk%2 Y^}J=}Z!DfgA^%28D%{PvegEnI1Arbc(EtDd literal 19234 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 delta 45 zcmaDpm+|>r#tCi;=6WVN3K=CO1;tkS`nicE1v&X8Ihjd%`9Z@Lkd delta 43 ycmaDE_%d*Un}WHXiH<@>Nl8JmmA-y%Vo5cl8lu delta 43 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 z
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 BV9Edh literal 108745 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 diff --git a/public/images/api/qiskit/dev/visualization-5.png b/public/images/api/qiskit/dev/visualization-5.png index 71bd0e77858bc39f26c9e6e240062b32e26fc044..1e03672a927119872d19f42efb2f6c3df95a52cf 100644 GIT binary patch literal 113083 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 z z2>L;dG{IyEv@N>!UElotYxn!dF)`>jK%fL-Ox~v}|Epjlr||)&?0MKr7}#kI7Oux&jZLWyK&|} zG(tF_tc<)o?v;5Ixxn633GK+jLSBjgFF@*Wnb~)OU5(_PYSV2(_c{ALU|p-LD(w2~ z)g=kfnsJ-SuGQVFvNBpcJUrB`HqVSfwheJ~cbcxGo%hjx{1VSp5;ijkNN7!gU4kL8 z;b42o?9)*9#6&E(=_$}}Y(S@8At6fF^44ziURVkx_U-8CSo4&IIlKkz7U+Nqe3oFg zO4W4C<=1_Ss4oaL;3N%;K)yPUJsiw{@(;bU0#+h&rB~2JX_##tYPJX98y;9#zM#&a zYVa`h8BY`%Rjn1r`jIv@HF5LsG@zSA&9#yo-}GN3VjDy0&cm~GgT19AMWS8%C~C_W zybAEfKR=k^!E!r1H`;W%y8~fo7c%S&bOh5wlb0x5u)xHl8dpc7oq;UKWw0E>vKyho z|DZnm8i|lkVBfVoW)AeNGAb(Q0qP=L!>Ru-3e{$eGo^!e`{83*kFA47dsX7OHNM-3nqtF?z~fMc>?tqL$AJqyd@rpbC$!I}_ACZ1SW8os8d zM+dWW?vWuS{?Q~wKt1}s0D$z+z6oO=N}j?Xf`BcD6x~ZQD>aDUk&57Uy=RUgq2pBp zV1Tx5aGIjqg!|k*AVEUkhZ88a8xq+&_6O1iUZ_I^R6ms9Yi~~}^JmKuM<sRZO^hJOOAW0Kxm z+)7GHrk{rXTKmwJhkkFzPrEYwTHq&dy?BXj1gN~{D~tZXf1u3mtyDW9`Zoov3oey! z-m}v45{Y1Q%5HT8#0kNW_?7@VoL2MjEI%dDYgoPkJP1}-EjsTsiqiKuSquBRUv36c z{CECcR7q*Or;;Kcce1fbgLh%!^xCGC^5o|INlgt}jI$~JOH&D2DcqkG--2E9N#ZQT z8_kPhKz|LQB#>6HvJVwmT$~Un=;cWIB@arpC87fNqHG&+2!u@w1cuns;p)#~&Z#ak z!lsfkN>Fy%w~i!Ua7Uu9JIL~P@7~?xbMI_X3+-8J{07)KVUrt>rb^3^1S7+f$NLoD z15{Ah84Py{nFDHKJZQzK28GCj=XN-W`M7yKrpE`{l=wI(@RdsY5AcnL#f{;&Q9s!G z3z1cO;;D$bXn9Im!)e8=9$fDe-pWCGJ2=?g6*jjiA(hQXc?K3uLn*Xu?RjAxmXA6t zuK_#&VhjoZ?AK>wJtR%zSnkYu8um%cHglUeC(U7=g8o)%m7YnffLIf zPf!A`D4v|Zo*mX@U+Pk*O}tgj?^iMFo^*0Lrl(PPj_hr8BE~}(qhHXz{$c%)@@Z7z zmDfwmzlJ0Z<8sa@c~O0MSb&#X#22WZ8`?Ap-t&4e9D5A0JhtjPnh-g!`L zD`g^z&5^xWlm1LG|2`(G8Lno*#L{+O(sPaN$iMCnnr^+gr$`TQ6y!3_-U`;($w>Q* z4($k3Rk)ts#%gqjI|NNbI<_}6REoa>uz#9PgelE!dlqyeavMF~r>u|9ugyI06IxO( zwu_^+vj5)lPUJMWvrv;lQqp<;5Lrn{B1lc>XyKWX=O`IK{q)> zTp+l7571$j^JjvR{;wJg*fQVT(8Uy!b&Hb-caya(5_p|vhkcma;|i<6>w5M`C83v} zEtu_fX(^4Y<0Wc7gzFCUXebG13s^-V+F_pV>{O4Ai2;9u%6a2L)@zf#I8<`SX(w7^ zV%y!-3S>!G?oFCfIDI%ld4%`1mws)0(mnN44#L;I+*kV*k{RlkWSV+OdAaIk&c~MG z3d6-cOWW|3B5mRh9GSNok9IROF^u%|_5Wx?BMD4;907vg1G3$N+0^(HM6p`Z`bc&( zUH}zvqAWJt(ce-1tOD_i+cL{h$1o3X2dZqb&=#!^N5hpN618LX)CLBDgt)v3}MrnEb-RSG~mfZe}8P zlCjsHaL}NJfgVF3^3ObYlNj6GCffr6lVE`N1;VqomPIv5KoK-9;|Dk6?E|O9yqIHh zRFgnNL@{jN3Xa+xIj-K@WuEu0E~wvLmchkL%qvYE4q9Cou_3!ezcFvBNAh9wDI-y8 zJ#Gr!Qeuje!%Zq;rlH=>a1uI!5bj9W_W-uG5rrk)*C-=Tx z#7CMXsSB`gCG380AMo_8z%`_*&nM*DWw=wpDc8D75ELH^HoepTV1!D>j0a=&a!Wx0 zO!PrqKc9rgAmW7|e`Vbc{ctB57;Si=5aAkyObCip(9Jj0WG)SsS`-h+!fM0R@BE@y zeGaj}6bA3FUhCN~k<76|c#n_RAy7j0sgd&lv%d$3K|@GzhGGU+Wm-Ox8(IgH$Rx-> zH|+O`lD@w_O@xnv3eeAhHsOi-VtbMJvCIoggln4S-u?S#P}y_}KZX{up0=eEPU&#P zTxE|m|6=TS;)fT(QHuxe-qOkokAvHhN?8P3;{Nhhie1(t<(@$dZKA{5aPRbP1|i^&pg{sSyfFpdD}elt z?_O+}oV`HW{N?Dp+{IbBb8SWlsTro-@B*T(L<9`_1?mvcqG@d4_@XbG!Uh=XNxt}C zfK5(L?wjN(sgR$&Ga+(b$H|eA#Q(#Bz?beIY@rR-ORe|37ibl=Xzaym1H-ZNHWZ&V zzLxhna*(}}42d`L!3qB=q9oVvBh3Ph<-DV*g2IjFBZ+>y4U=qV9v&JiHW6%#2LHZ> zO~eI61bd&07U5Y|gmz!jsiL7lF+4Kj44cIrQbgwrI0gf$@NwXKP#S@de3zeZ;lIZB zneeq;N?;y*#fmama-iZPYVT3Q&zt35aMYgw@h5HVIr)SN@p08{?T_vU&mTe3NbcYm z`jPc^ef*SF?p`_OklZnMkMv16HxR0_Vo67I0yHE}woOM89=2ZtY@g=gvTd5o!9H%U zF7TBI3PM<7mDdwvog#=0z-SB83-m=;VR*TIFY_LbkdFEunBmd&3uou`1f$RBq!JfL zg?`P{q?0^lNVI*Z=D|aaKUUCs#uEqhCFzIli^J?d?U79NtU3 zIdRLiBcKhE*8-Dr=S}U3Qv@%1NCI$3{4K+?_HJ&}FrmQ5y|aef3x9nPcJtudV$k&! zC=jXr771xM$zF{fi>L5$VAcnvB@9;2fxd;Q6kP=x1o(;tK1OS?&aZoVqK`uej{~lqHhMi?nE)^dDSpBI6{1jvi2ieH3LyV1 zE-qdHEeE_aD5d-DbX4ktde|6&`D<%y3tfu=GUJo~`^%aBA@%(&gvoWu^m|!-vV9mgF%e-k(ZLweo(yGhZFcN=hAw?MZv#w(DVuj(uU(`p z9`F=zmXl6!d?ST^-jaglc%phkMXpXe8N?ZUF56(Sv|BVd+52z#tL^OD|@f{M#SBznsRXMJr7wY+JxL!lkO8M|UdV z8|P4iA&JV}3yBG2S`oH>$q^EJlh}cO)$XsjY{Xaaaar(>;pIRSEV6_bL&l=$czBo6 z$`hkcAkXGnX9)T=1ffdI5uJ^pN*8kLV81_PU+~k}joqj3R>>m&AI9E09LxUyA3v{) zOJd%!-m#DJhlJP*F&-N1}y@21#@q8Q;fA_xtmC zAHU=G`~HsOI_^L2)peccYdoKi^#l-={L88MI0%?*5D-x1uR)O{GGou-C~5Ynw6qyE zidU};fFL&fQQ0if$f9^TzGZZs>Sb_lon8^0Ub+iX5d0{7ZIq~x>_H82RU^f~V)oo4 z>freH5R)^Oi%vFE@gX=*5ztUjgE!)@+6n@{?;R3U^<`dN`j69w;a{n&h~&(TnmoAX z;V(=p?B^!oEQ_)@l;y`IM@<7e$DNU-S{TEoZ_8gwlVgD`yZ0 zXG9Z&4;jpWy9D4X*`#d=U=I_~BMVqShT`sHBNn#^fs`3P&*C8W!b1)(Ur`9glWKU5 zA}VJ`?m2!L`^DRh?xpiydLk>;o6i zfn4Naeq9oL+MLqFUoEb7xq%sm`Nn%nJ9{d9T!cbzpM_1gllQ&UKWIMO+`2g zzw!_}(p96e)c#743RYNkvX^t4>xok1o87g|%(zIw#BXOUtH@=`mO0+D#+yw_y5g>( z7cNM@=U%+IPsJdiSBge3G6bJqvf|{Mt;|3zx0P^Qv@yER!Swjcfny9m5_rCO)Gor*}O`>C#7PG94geJ+``vsaFv}6v7sZJ{m zuQcCKBO3faL8S<)43m?g-x%reULUTEewwdR>zWL~~ zNRi&*BI3*Fq)&G_Mc|Asst<9O6^j~(opCOED3>1x8=y0NMxlCPI)4!wT#nYfGf@f*h_2#+;RzB}A#irTl&%{lg^&Kmk=6*(Z``GAMti5OK z-S^))ZDHNo$w$ej3bD#1|Bny$N!Eo-tHnoYp^0@xSnke)kY>RAuIuR7b1N?QAHH~N z%3%PBhYueHaJn6o!gG_eoB4=cnqQmpK&9fAfqdv+T>+5cW5>3P1wA3D{?fs{y2+jt z7RGZ&mk1dL2p9)^o!dBkR5t&UF!3dO+Bu-~13O*&sx3}Q37NSX&3b1;-ntMk3X|l9 z4F;9$eX)t={WC3GLXm5vc5&puo{3lO1Lmb0lplSt$E&3*C$ zFd9mo=wZDr-1=7(Q12?uX?wf#XLSFT&XX`0S z%;g$qyZ*g__0OS8B(=ca-al^HsXf1@MWm@d#aVH3(GuvkvthB-b?(!d`F!<@5d9Wm z(6*BPUtkQRZn)|yB9}OOd9iP}gx1xy@MuG|RX%a!Y}Z49(|7ncwcj~wMUU1ykTRFt z7~+|fD_0H@BY37J@y2>0bxx6=jed1AiG>QQpT$+V>HhIk7Jo#WlI%48-WgzA;G~rt za=GEoCck4sTK`Hjl1<1q?|U_=b_0D6tq|H}z)me8g_ELJ+C-Zuuj`1@s9I;bmhy*6 zimrE@wb%|eBBz+8;$C2qO^ftgE(c_!53$Q`DqNc9rMwWxxW_6{((s&4=C;sr(kKQw zW#VS0%a%1=aYk8YPeMM~7=Grw-TL+F-9^VA1fO2emmu@U|8Pf-kG8$KZmv$|$u+4I zsme_Zrpuhyth3XI(&Ioub~R#}zutaSZ_NPzdcDtGd)MH+)YtxZpWg(GU9oU1f{w$P zUT~cG<`Wttfx;2Rgt%e%(B{#?179}qI`I>uCcSYWR$!Kl z5h59Mw0NW~ZeJ-iyPp6%tbmppk8?68974uFSVr_@Rh({N8@s`koVMum$UV z7w$r^w0H+-2gSEeFWO~J@SK`(C3N3W1meqRE-))jydO}DglHX=Gs%UL7IR#s`!>zu zOe5o7FRw<#@v2(iXgxvfkz9#6o#&#ik5WUECy>d0%8)9dq(L?IZ|Bx+z$zkkkNd2B6o){SsR|66sKYn~_ z-KmwFZ6jOwd*z51%xCu8u`1EY6h1bnaC~V0-jgECr0W{pdlP&Dh(8k`o!TD*dpSVz ztj!-FGkZ^>x_hO#N7Q`rXqUg|tB{1dM9OjOu)Z>*^1t7h%X9Lt4Fz&}eWYmgB3BrC z1eQ|j&64#F2<1R4fe_KV2+e??r>gq83njjkNJ3@?$;iRFiA+o!qgh}G0kM(3O)}Rv z8wd!Xb!JJ2M|(_ZT}yP#PD#Dk7?0-g)ySkRGL=AJQ^G{L;Xhs(6clv#V3!)o86=42 z)6rxjzlR;U6~hB$sP72!^gfZ9T*n@3UtQi`mfMyxmu=>0FRSLtcWrd9q{D2jR~ki6 zpMU>_`$?;JklPH&M94Pqef}adhc6zccGT&NCp8z?#~Ytmi?fvo8zR}|6>qn@*6k%o znT75>o^RWDpepWmmfb55sO5X#@J2QvFfgbt5WNOs+2wL6^5O2X=?dra+K z68w{a1jyr5e=+l|wHJ637%er4JIcauHdZ`|&Fm`swO<(*#cwj#{r%2S#kH5Jdo|Hu z-?EfJtC&>qBU*^+faD5PmUqd}-+_T04~;pjY&)s9R^~3>^GSl4IyTjD{btSg>II_l z@A(K~0v*=k$Zf2r3R$*l^4_8d3@0X+%uhT+20$ai;e@@j#Qf7X8Jb*|`0%V@!<(%3E`3G$ISC*LHTFuaUJ7&j zHlVxf0f>4JF1bgnUa&OVqdxvS{eh>;Ay)i|pQ%*Y~!r zT!Q=!A=tLbw1HP&)@jYx(l>XatE$@&hq4IBDR6UAkBm}O+A7ctqNjcHFMxQ77tl77 ze?55v4jojYAWrTb9d)&qJ%9DAaV{SlB&MK>!G2dcs0RlGL2Z24?pVA0l@*yTgy zs)u+1M+hO$bsT*FdB!3+07sSnUUMywbXhd(v+D_th{^`SfAeL6jt2Hd$n~1Mq# z7L}80hI~?FrZ)1$74v`^>yPpoqs428Z0qA!4Ju=4TV+6pvjC>dl-k7g|UjRde1RKcDI{%f6nNE^~z?<(n zyLO%1DbK#{@u>~oi1#w@kyyRj?L}|i$dN>p>NriCB1Ao{)#VeE{+0^jr6}29LMDN2 zGRFogCIqDZvx2odL4EP_@1vTl*_~^s6oAteCG|QAM+(y7T$nV>c$%A=L(|h&dc7?o zRZU82x*S$?-rWrHCmEI)pZh}GLZ@`k8Xpw*pnf=2A2d*&ctxn5V);4G{SV9YLMSoa<({eXls9i)M@ z-?CvKS_T{Ae?G6p8G;3|AnILvyY)qYBdgh(IRJSejMj`iHQM=aNl?I2e7vZnB>V1N zPEcG^-F*LwQ7el$#be5QLwtLO-mW4hVRF8P)~p?#;f{ZZknf_+pLfJ* znL_0D;>#V>Bh@EpDo}!#YwzD)ba$mEck1yuYg|BTq~444wZnH~-z%0~dFkM+1r;w= zXAKeIx)CwSOF?Iv4R1_ESB%W_*Pc4_<$Y$6iQUzJ9-|l27pAA(ASf_1TXkDl<>8sF zJK2rer$VE>D6RnXUWHU-70EyR>>L;v_$r71HU)N{j@H`PxIX!OT#o`pJ=l}6dQtWc zw)Ss@3Ts_@KLj`&d?&>@SS1=My#AbJTG?T)x=z2c&GDz{|Ef9=Wr4r}lhwZK!9*9) zR8BJNP`TE%$iU(zO_!sqtk0T3UPhO^j9%b37j1||n0bQOb_9-Z7*a!zMM&Ceihfw> zjYNNfPI~omq#L#UA(NxSo82oBz&3(ww83pco9Fsuzxp-#x%wRw4{*bSbwvTc;r87v zZ~RK;qOJw?en%_ zrQ6)IqxbG+462CW0AmwT-TTb$;FIum$lGZBF^acN)u;;}7E3+;S!L;k+Vy#VxXheL zr&RRh!C=XZNEn(>(LiBox_h_Wu}gdKOZV;-hC~LH6zlzW^#MKXS^gAx`~NtH*pX!j zD&HnA>y!Tt5tXBS{;Eqmski|j;?_PI3k5Nrn!Et1#36I)?tOOtv)}viy@T1GH?D*u zMXfI@YnglCvqjIkBEpt0*^sZ;YawiN`uMTFyk*g7%5cu0c}A=ZuFruLMr}Sc>%6{A zR$B*-RprVN5_XdO1WgdTydh?`s;+mW@&ncBp7l@UHL)V2Pjuzcz61|)RXCAZcXUL* zyI58qM-+$i$CW|q2t8j0;nO?&NF#0EnALOAXYdTPdWD3AxBunm&{3Sq$k_J1h#V9F zjR$DowHFLMYhhe5S7`FSpXYQw*FI&g?a$PDA&xp%C43+hxcZx6_dLIu!*dg|^?|ML z)+Wp&7F8$IJoaEwiEu*Sej$I#WY4gK|GE5}99M&hWh?kcX7+OQo;h(c>iz_ObbCC* z_4~x!4W-_$kj}XM!EI5(TU(+wj{g=Fn3n%3A&Pe1`!Px`{5Zfce)d)pukSLQE+{2x zk36?>j?d||SVP2Q|H@JlR3dsg=!8%8iX$4=TOGlmlcd2qUfTanXz`$0L%T+yYx+80 zUC1b$)DV;Zgyxd0)~%l&KibkzpA?%7u>h`0mCwl*STJXb_rHNd>Ixjp$Nm}A#6u)e zXUI=M&tC7RIy`8a3I*Fv4z<8hW@>Lw%Ed`p0{-o1S=%D9Z)!Z2^;Kr~Q$&^6t1W$&ssdWviPkhR1{>G`j_U)h0f8Nlm_k0bL+s|{Z zwqRtWmH(yCU6cR9f_#N{aL9>#H7DLf1DPCn=#wf)rU)S}T*&GYUKuj&3(Yy?TfC^|QRf6AI3wqT^y1>fzsJX`w=#(u zAVo)gJzSkBkfhnW_wPl2uz>7jkHw2at4oTA7eo-(cH7$lT^tDn1e0Puxnpt9cUx#Q zP}Yo%k6*zbfi&TZE8OqDyYjR_n+JDi6iwq|G4#J#@6c0{vT4WxpSxaqWHEejuIE`- z*NU``UskJZPi)XV+1c@dI=ESR@v{q&W$harzT0kT*mAT)s{69;cv!-^njd)R~;XyPVoCv=ggDLC)aT;xR^}A z5icB`gB=PBrJWw_SvZ_`U zg(vuIcgKjrwTP7oxVqNLEcsATF8q;_exh)hVG*3j z`?@}ua8TrR);%)jej0nBx;GT)5I7(3c2|?~(_;TgJf6ItVlri6BKFdhP_DLSF!lZ~ z4Tkfc#w%lPVrG)5xJG3**?P5ZoePJ!F{`A+^6lwuxt-Rd^#ou`x!rCWCVSLwpZ7LUNff4V@x0k4d*PSc&YtPd^8G zLu{BR4cBzPC(?YtdXb2}usXzqFe8$Nc9g#lj(liH?vl}g(N<@@MQt@CzvS#28KZXJI z?C-LEvR3{&NZhqe7;8L`2F`9 z#r}sWjRSimKbM*AA6?-3ufIRP7RU5D3$|SVy@Q6s4_&Nr3HuiXoJs!8FfjGeWfnd~ z=^O`nm7$vlZ~R6{m-qbJMTG(v!X|p|9GudT~!*!jV-m+*bBap1v&f z2JpFfr7H8CH?deVr}nJaSwO2?;Bm4Og_p2iPJaGQM{B>oROi~nT#A(Ty%I6rC|Imw<l3~K35^o7H20^xvvE!l%#e|yXUYT}q%nhAQK-)04cZ@!<~w@3x~9$*Pq;rTXq z?vIX-p1gyC?d|uvA}yZLj9)Dt-0_n!I~mvi)guOXLtjz!n*sMD7(o7eP1V!eWr>zs z|HINjeAF6n^jMGFy4mT5OyyXUq2uYR#!80hjayZQHrzSr8Mqa|Il>sO9X3tWj9%}c zb;qy%;`)}7-v;`Yur}6R+g;h?<1)R=@S)2uULOU45X#SvW|Py40}LJIi-J$T8*+uy zUa&rSPSWt2AiZ$YeROCmtTq=DjkM7WMa4~X;dMo9cmG!joLUr|iN^|S5Gub>VPgnz z>t7Cx>dR3ONw6{_>R8Cen6p33XxmjbUTIjne7J)}GwSiC=*EpBewv&l5)~R6>hV2O z{Gw%^v2D{*9WE&SNU8*7c*ko|F4Js*3)I!qdPAZR&60(lr>EAuXOZ;qZ!^kSlxY+^ zgGK+~_n4f#+jltp$Qv1BGP*G{p#sByVsM*6`CSsmX{LP-WP7eT!G1>R?OU6=kXC6M zVyE3m!sNP5iZj0%l#noCjH3vEDG)BG8K9WrNvi!E^YC3~T*l(eKY^Y_(=lQ6S?6Kr zpMlPGe~zA@KrRfs{xe+fIAgxX&PmD)LN-YLEm(?vZN6goggba5c^VuuEWXHMvw8bO z#-Da}NVM>}Hjy@Q{rdDVQ!E(2I-91iMG!~>h^lP4W;lWwUJi)OCFLSyKR6#Q^(8yj z2XS1l7U3FhT!h+TSw=#r9{{H?(54F(uIH$i?+Db^@WA;C_PlI>Wc8cls zOS7eRz*NBIUODxS*E2gAHz%G4?>1jWXa_h1U_urBF@&{*kXe-;?EG8H<5NCrO$*8GeY|H`1@sqO! z>?)r{(=MWiTX}?HQa4PWj3XC_>r_*-hucSStt+peITV#U6cI#NXiXu5+eVp#`7oc8 z{9{LV^CtBToIBOJ#YNpGkE@Z(8#AdMJ+l4W`t9?UPL?p{%O+1KTK{^3wtMk&>2L+j zR7x&ZDvrG>rsGOXy&l1tuDJStnyrD;-i!Ajn4_vvwZ&>wOkX!;n@%(OT3Dm zT(@EUp7I?ffp3V@2m``*eV~1jqSEU;ru$_~x7>x~@~5^kPw$`6*wp^`*J+N-`zIDr zKTZxA4UWsG&uss}7mw_|w)XaHp!4wE6$&rvS3F{_CM3v4&pmHd@lJ>2ptx6?xcHaq z73{sjszxO$%a}4Pm(7g#2b8|v!jKYWZoUTU2H;$P#hq}BLTO+Xq_?!VuS~DkiOt7J z0q7OW9fkA%)}k@7Y7P5X0A7sgD&a$DFi&N1JZcL0B*5Oe!M)h;SnT4uTYV2` zeOe+Vyyr9fmWAfE8j8nmf{V!A1R@8 zCcFm(c+-tQ`UqYDl|Ul=wMUr-Z=4re8r%a18^1sUlqoCw`fF zQZv&o(KYmj%7ylGB>xOZKsXIfr`+9@sIp@9-3&^jmQPa-Pp5ynOt}#|GW@Z3L}c~q zDIH$X?1$!~n_S`Tgg%<2f6yD{j`?Jp8_p&jv(KG+Z{Re0lha^otY(v|mxOprz`jxQJi#=2IupfCOiM|mB~ z8Kl*MN__R>5ZX7=sMI(>nukD(pk%BKNDw&wDuj`U3gOV$eOkvBa4%$2pEj#;UAyBi zE$}~OKx>XMnFNYiJf3cAZf=^}XP$1bzAogewAsHRfU2sLa*+35{F$srWjKG9?vtCP ze3K>`R=Z>RAbaEz;TH>K~)wxv-Rp$FIsky)a}vB*^?_;B(wgV2CbG(C7;z3wSOcrBq+?e%ikJnKUYX1Bhc9ybv0S2ti>_%exgeBFA=e(xm$H?)}&X@+ci?q>Tj zC4e+V1WD}3WiIFIu4F5Yg?s961j)ao?B2J#O=<$Tu07ShnMFv&h-xc*q&keTiG!4e zmC=R&EsKisI}?_y4+mvrWbkIU3E&VJL zn8wG>5CUeox#LiYyr-Rw%Dy;!bbHNZI$j}}&b46!pWnD$F+Z^@VXlAE+QcR3AMZ=9 z{?@f@R2Y1*ufm$gXK!s-1rPWV6{TW278_2zY#7nVpy_&7!hOI2NibkMW>JFTH+>X&|}^b zK9bhIT!LmTlC-@Ds{9-m>a6Rs;cWEi6pGZ1t27ncCIm^7P&#-bR0>XS{#bl@FEg+y z<8#>ryh2rPbr>~GZ_unKn*>S1$KiA{wGO7Y=uB@=Re zRPi7&v~Wq%I_}Yoi)bgKF=Vq!qBcHwKf$z%ll97N3cTav;6|4QA2Ny*r01p!z7F73 zwk*{HL2_KX*!mTF#aT_s@D5P4%h4xk#-AO7+wHd{@; zI$6qM8x*eKmsmWS5wxdt>HIM~-%JUD(tS*`o)x5P@`BHAqke+R8WbmH@?}4Gpd#IC z`s2M!@7nUP&D(+>r5Kh*ftqW*cTR>_BfR;uHCPJg1j{>bYGul`d0rn^KbEwCEP?L>+RBs@#X8aGg%A-jOL-;{mnw4AGG(FFqo!nvkpD(huv*x>6loXc| z@!C}W;_{-u$nMImF$jo;5<&9da{XgDcL(Z!Ce6C!@`Smzu3bu6Yn@*Na3S^Y)n0~p zRG_s2GouNRVk9%yND+%UII{Bd7ymWFjvf`=WlKL-2OgQG@(`d-Z}DnYJG!(Pd7Hb) ze59t)1?g+n5KId$28bPS2o&VsQ7H8l|NV8TR^J+WOmzF&7I>&o#^vr7hvLdI@33u? znKys;RrSxxhl+^mH6-ZAgqXzLqIUFc%N!8);)J3Ny3f(gCTn>jIf*d5PL+CQrEPcvTdrVR7-i@#@Z`GEs zH;)9CzJ$#kO+K=Sk#xs;seZ%0Bb%=Ag<5WB^O>fV4+`v8hEHtM{XR}J*VG;F+_Gc# zXN95X-ezoUY`@Im#zTVnhS*%VGn>yZ5Q+U=TgAY133*^ z4@T+;e?`9*hg^9W`+h=K25={OaGCFm6HAW_zZg&(-^9bqi-^8uyu7>*0QEwav~|Fl zoMJo?H#e~)?Qpw|l#I;DDyPsIm*+^-@WBvIM-T)BXD&tcos0VP7N|2hNj9nG6b4>Z z&2(PtH`ZuNL|Dqq7K`s)GRMn3AY9lHA=v`5UsX)ImiSll1d`N1kAA@-pxUV zjBex%-$-q)`Qw-|xZ4?uN$KMI@DUnKIaqG%Fo@*q-Wiv7DE*d&agk0Yx(6h`Fr!wO zot^a<5*?k~$g}g=C0(@g^*JwT8bH0seyq#t|EZmz5rO0kxS)K_GrA`+iOR5XhxWIn z2Yu@iGJ<$>_)-;2whSqE#)i;0|KiR3G0pFt?<@rCW9wI=j4@55);?1*8RLxa@iw+UpaC0xF|VtizLxC?Pp41~(}TZN(@2L=lpnFz$&Tb-8& zCw@&Q^XTsjdMCiGP6yAW39pV3{nsi!pBW)XxpFCUjJ&?k_Jx;utvXl4eo^9m8C)h_+&R73y>x+~YnT-3=nE;lKU=EJN7$SdJ! z1N65&tsp<5{EGEI$$m@@F_F5(Cs_1yCLafELP20Q*>zu4i4eO(`7#pd!a^s76q3}y ze`6Gkf*N4pg6FF4J0dvvfkXI$zUYNhg8Z327^_%!5b8>K+uH#Rg-@}QLHLOhOBIE}gcn9H&P5=?8O zkg0*%mvk=!Cxh<^#V?}gaRu@sQg#JcEqMm{>gAjIj;gM-$v?H_vI)Vxzfk+n7F@sj zbMHPMs+T4(Aj=7)r$w+OkW4URq`fCLJL8NtPb#7)EqvvYqrttLA_c%as>y4J9CKtj zS(rgq?*#b_@)D~&u3u&Xs6GA%cK^S+Ycn%SS=SQOsepxLSqbya<`{ zuL=yNCELsrB|d$-4_z|+tnj{EFNy`mgz2a}a3h44yGlLL&R3fwU)+Z>D--v*Ulc0vObEy=W@#qY*oqN-H4^k_`kZg6hXR<;|RoW5-6 zdwU_hl^lzK4s2lBe)O6)MgBE%6s?`{{^9Rl4X6;5l-svW-ILB2^6{*p50A-mW*v%tBA{_dlAdAS2o-(QiQE+ z!nSk(%M$M+<c4`{U{&U3R+7i66!#NJGWI`YkPU!f?u+82=DSzH3aaSxgRfCRNM6 zZQ99tg&q{X|E*Wr=b?Wo)}=oWj^3W^Gr4#iKwqsf#eDhV>a@7jg>VN_Z@9qm+Ey4} zZ`I$w=;qLP0{js*jUfPKL1!UgVU6~d<%@ORhI1FQFfa5ItseA;>&9g>(AoGOo4#xF zdDD5QOGtVN-NWwPTfckMdNR|$-er@&PUPgfMD7LPMrs(3=hU5(st}^{S@co6Cng@q z?tK6}oMKcIp#8@#{H?ZRSIE=lix&ms#(R#79?o`NZw$Gg9y%Bj`#nWl{7$MZ9gQ>W z7i7ExlsHZ6CY#0gGdZjoDASXS)92ACDk?&WfZ$Ps^L{ZP;x#oxmAADF1vmo;Ak!03 zvz<8cWGAOlKyyl>AzrAb9Y--+2F6O_P%+O7!UWP5{L=XoSmW!;)dp;=F88JTKGFnI zq=;9J@NbhuFFa2W3JnywhPITpQCQ(wF*va*XszNT>s|9ZyE(c_`%)-3T6Jc95EEO# zSdQW!@hh+J=SK%-{PRx$!F^iDxDy7h)QaV8mjqWmj6#P}pJa#glA~1W<0`5nD|4d-Wmo^+A;eY#WX&1ElJ6cxF zg|nUUKsEAbe0V!}8BjHe0cYFYm0Kbfmus&gMbuc+u;h}l!yEkJoe;EBG2}PkCsxO{ z-CX&0_XIqxEc^LQNYQc}!AIybZNANXbo{{OOQ+D8T_IE+%88~IA86wwiVf0_trxP% zal!!K%&Q&wFQ-=U2saREWq@Dfs>Nz~9sa))Dty)VzC<|75~4LAN=)=~_ zuleYwywMXHC9sKR@4}a?*vyzzBW_sgBT8Br81K?jTr$T@-s37#>Ed(1;2PA2&xXgV zKk(r^=Q&6*`}JPtjYX;bNpkeo2#Ax+!a{B!C^y;K@7>tMC~;9LCZ;GV*RkFG@qXe( zP~*#DW@X~NZ}kdf&}071>Zh2dQZbw{F}NH8*28ahN1_iwb=~uJ|DDUf9>9~&gWKrA z?{>TE(~nVccTKh5zl$j)9*u{g2b#uA?k(v^FCxk@@$7)j9tN%&w_k&gfZUQH1OV;l zX>wMDLj!dG+K{B^>?l;g$eD2%?XQpFpARemIE8DS{2OG~fLx;HuCB)E3)#u9LPixH z?hb@vp`e&8?F2}GR5>~}R!dxO;Ft`!V z{_w0%-IrmeB8`z0rg_K-h?>WlviTs&0x}2q_XWqPKRwBWA90LWLP$61L$9w7uW~XA z(o<3tV3(4W)pm5uYAb=_$kx1gVv|MbU8$IsKL>LHdbEpS3IyV!d?i(l&JlBvDjGs- z*-}k)ARV1=-@0%-@^q(|1#^^7M288CoEik7hMNvb2xQH|0E6PK0^wHQZaUwL5ZS~W zmih8D*ZSkbF+ex1haDfb(^)3pzIlq|HiP#eb2H=uL8*l-<Sdg2z+ zy;Y~aT*2;JL}s*-_&W6L&@htrW~h%M?ganNYoX%KQW@O}ne|FCJN40{ptl#w{FCx0 zm!wQ=`O#G-jBrFUR}@Fpt+Dw2(}-J>J~!9L_i^pu?;uctP@&!GUr%fU@?i08u2!^4 zdS>#LaXGujor3{;pVBnTA+I5$y8oEC<0|6*9xv^8c;}U7aj&^O__au<%RRFX9wS_G z;Csj+M@Vac^byGbOG`>u)EnIsr0a*g`1)x#gDL-f!*T9}ZUZTsLo!SK)GS70Moo+k z4tm*RvfTsB=5`Shg9R>b(tk|9|Td07@g&9&^=*2GRtn*7K0 z#9@UJwbN4jECmF(3Yj*#^gVhU}H&+#;cPASG zWIb%~hT83-RLm9^7k33nVt9Bs6hZ}$=N4*17YEac-N{kwi6>7x_CAe_h#=!5pzdh! z2pYAQDrPeJa`PX!DF#a<1bkMXV4f3gjNZ#Rz?WTYD~D}n5ORfhO-Q0n4PxYA9Q~gC5<8w2h$`NzQWGsZ$_e{=+TW|aoa9O zas!6SMIiRt!Xl}q;-Z;*Vd6u+Vc3dvJiAP)@iRPuukT@umE_)gEU@%v`qpEJ79%A` zDE@PItDr2$!ybJa_-vl}d+%>cp&zoUTG~t<9M#F71VX<<(j_>IPU4l#JlvN2;O)2Z zKd_aN(+%b9N*s1%B)%hRi@V2Jd3Mm;LpLX3vCHZ#o=QX9d865O*YJYR)Ay5(7U5b+O2D(HFPf=b2 zmNKZ1zxdd0#A_dl{&lBaKRvYmI(?xAB)_pGc5GteQh>ma7)xL3#E6KmTUFi_TcTYi ztNK;#i+)1$5@AmvViPxJ%CmGbia!^kLy!aL0XhkNn~u$$6dzRWxVUOk1?uFHBu*LEZACvZZFpC z`}C9WnHVnT4jGD&+t0rLywK0+*4Vob^kz!O>La9LZXOgfOb&D-UaTQrJz-Ynx^^Aj zdQ|X#)gD7nqpiyfO#Gw?S44#c8F?lRPA_r^;F3)m-TShy(eyuo<2bJYU6FZ$s4nN7 z^t=qt#cVhGS&SR z4&f;D_%>N7koapXp=RuTcKm~KD2C8~pMrbHL!k@#)bKJs8w#lC@j)7`gM8iBj$;?Y z0)MTmC=6QS{#)`ilW|8Y>!7z_q+~~=&QVI*(-$#umb}m0^)A~8Cb5LYkNw;-GNU_L zzG7I29!eL+6Td+1>09@gjp*NZXf}2Ox5@R^Ye<-|7~OkSVc#K$RYgaIrIY5`BrPd{ zzka+fj~x1z6@cKUy6Np^pacB)5GaXAV)V7J!DNPH6s#^mB|kQ)o^}Eresan=V*Z?) zv-|4(ja~@JL#~9J2hz0(7)J5H?kIs}(UPH?ZRu|Ne>puxAq&YHqG2mhy^xWn;3RH; zKxT+@aCD%D8xew>naNwa*PGobPZ+jVl(Uu6)gParN`8>HJpavS&u{9jn|k)|65l63 znA#dU6Ot(UQIKw#M*~ip(X#dziWcl>RPS`a(8_K-ljsN^>vtS~yFcl`2AvY4hLGl! z+gfW<=R{X*;okRau)49#3#yY%Ffv87rmt%w8+{a-ft1NONm47wGexK^=!3|?ZsgqdmLVIaeLGB}-6{V} zQQh6$>F*Sig$9cw)%Z?f8_?j}y(p>^EI z2y)cE-r9r4wc_Z&Bf%|?8V0T4`U6As zLFF_`;B=+F0DB&pULhSoHE4TniPr@j_OCx0XoT0|ggoL#B5Sue;*o4GIYZv7qSjsY zq%lxob9%?8t})*)TpBBFcM!KjXe%d26;ukU?*`cLsRiqD#f+YNvgSsmXwxkHSI?G@ z|Li5?g|1|L{NTM2c+W_4TriK-o}&^cH*o1FTg=8v?s6p};+g>{?Z56CG;7$NqG%jA zI~w#vKtMoaL2!wTMKNARrOEecUoX+cJvp@JVX~_>$h<_L2y{|hM|jPj5>j*TI^17A ze|1h~pZX7baVL%xQ^Q(J_{1)ATX`~3uKdseYPKocPp{%}=82Gu(dPqJ!6Tb)e>~ko z7aU$r{ph{&xW);rbS+l9ZtTXA9yb0)w{3rb2x1{QeU!@O}4bQ zwpPf?>z6|q%YHAfw5`p(U(@_j&O!&cYgd=>ftnTK#ajBi%+<@j|Dq|~&JD6%lY6$o zuWNjjwv)^Z{~1%}sN_y}BBJizma#F`|+XucTDSgCaf?)N3VO=}qDLn4Bp% z!d-gGi_)XA7|6M`jg9_|YvDOn#}Cl_2#MOs#EN{c%ntUG1`c%N>CxMTz&w!aLd{E_9^UXUt*W+eYaIc8w95+f9lHkr|WF&^J2y zvdN7a8o!|crAIE=SW}lbZ)!)Tc%TnQ}v8qO>tkJ@ps##huQ}yiw(TbXUgPMB6hucdH+cI z0KV0sAGOp_jrhf#4n#!%vh&HwUa6jG9#=ExL~rX4vX&2dv6}IOFLW$dFw`0d7HUPb zV5q9&Yd`n6I9@in@Vl`!AozCZm;haSj!TP^AwFL5XzCI@yX~7@34>>ZQE|Adt1A;} z%tBdyTG!dUnzNW{Dka`GH+fR^DT=0?{`XGnBvw&_`E#b`n9AHJgh=kL_J9}*3+Cjpv}tE9Uyj|DY3={2`u<@ zA6*H55WXr3DXhfMJ$IHY3+qhzX~14SR*NIsANwocp`i{Oo2Aj?4CvQz` zc~kR)7*!>+i0c{~F>zb^n$41ICLfm9R9UWP->g6VEY2vsH~7k{<>1YU_lxbnge>;z zHf~k4U~+h5E8@iEP{pqswv%|F=O+3oPD7;9Q1M0FP8s58dNu4_YwaJ5rZVq1=4+cPMce3nOshtp6d8W|Z88V`1LILN!`JjxfC+F{_c{DSFE z^T(Vs+leTO9w+_vaH=XJ+W|e!%~%mj6$ox#JG>mE8fSV40jiPiQmr(i@O=wP46|SH zpu9&tq>#Og=T+^}^5Q^B>&bQA7xh~Bt*{|aM>a#P&4}!%hyGbl(3;ins<;gSXfwmK|D@y zaBv4_@;B87L;u(w6vx*y|6?Q>wMcqfrVQHGRdTf_BsWE!1MwTqNu%48f%;N+!$lPVMh zw~0Qor1-8RC-c{EM*;m0qgqpNc`}0n&y-r@c;=iw*763eAA+5+2G_LaMaKr^zRS;F zxBy&pAx(nQn-@v-f~`mFG}$$JWJIE8#ZJY)C{5GQqnJ}3Y;Mc}lyhwS2c%NGUK~b? zcXq`}|I7$HSGCtfPRpNPQFD;rwmZc$Zp!cI;zokqAd_YtB}hMNM&hS&nFkyhsiAkd zq<0YwSWcy-$CA_%JufMWaLn*~7@r!9%<(|UgAeJFo-g5@yuBAAcEmLAwc|F7j*0r` z5jTTrAVd5YbuDIcxjN-7ag4Dw-pG5>{}f#>iz=TkD6iV+j0T&Vn;WHvMsV=c%>6Hs zIpXB~vuwjHopejuhHg#yZc6o3m7US@pUY!An=PzMmQ)>I?m;nGr&UC3&m+XCFl>u! z705*empvHYl0KjSL?<;>kTjDDopJrp=y4I*xSSq`?+3vO9XoI^LH;xA#Q8Nbb z(n~6xOgd&5Re=wt2WVraBSxAbbP@e=-=U*{0S;@wsY@p`@HtR%;4*4vN^8gp>X`9J z#qhNmC4^A~_TO(E7$xT?A?y^kFT;1n*6;bc2k#K?13fRE54G&ymS4B1akSf7I4pQ1 zkAdOe18r4)bzU+n0tlVFSgv-RQbK!lf{56!^%v^ z6~m|SZoieKB`NK0X)!13#-Doqj zTB2nad0|jQm_#&1Dve`zA7JRGDVwU895)j%Cf2T9OG0p{O-Y6FcOe1W$^p&0d=4Xf zYxQst>E=+y>~1ga+r;;5qiwj7&5AF6TYR$SHr=Hhc|VtP^AVLbm0h;h$=8<)G!p7* zY%$d>$Yj4RyQkzkyM_sbC|Ajq6cujG)cyYb^1m4aFh{4v)xQv=r?!POw@XNxzxI1a ziOJ5i%*(ROLyT5>5)Qa{Rt>GqtMIKkEAv}&+?hD<9*R5{MR{PBW@2pYh^b7VNZ`is z*n9GZbh*|Fz3B^zYo#uR9^ZX9Q{9WHKy$Bc!&lq1=XKq&-481JMQT!CmmG_5d|v2C zl;ckA@o_kGXepK*UVTqS-s^8y+f#fQOsQRq!fz05+PMVgDQOc+nNJlxmp9VgrV*H4 z-Q6wHKQMsFNdj+XbiXlWc1*>Ia9s5a`^!jqKYb zEi`lVOpI>t^9bfFbY7kGE#d4xM>EZH;jah-et=s6cRlI@gcpYH>%1#~sWlEMb&S#C zF+5>1;km?VFCys4o))T>2FPEkw?#;_e11P1qnP($EZt$LBBi@*7N-Cwj zK#U;9Ti8`){JJ;s9XhwzKkQA}jF!xDivwS+Jq0f2V9E|TXve~W0mLR~{f7@Xfk@Z9 zZ5ioS4aHea)G_HIV$|y!FWo44<2nz@DjeF9xH;WF?gh93o`?HUoZb_vsn^VEoq`(9 zcMUFic+|_Qb=cP#(6Z;4SCKa#qhQ6h@|^lpSssq-_L)#cPi9LYvoCFvpQN;}3}dzs z{UPRd`3vSA)-nAaLlBs^l^@Q+c)T`KP@>PkcETrxS*Do_@tCL< zATlJYUL?pNju3;k(3~~9*I8#fii^k3iRrQWC?oZoi_S=0b=xJI7KoAt=X6I|hu=|DjwuDDG12#it%BCO zyrg2n<|ESJkLQIy2x2M_d4L~9F4Q`1xb)1|{sqlvEqIsT{zsqeF|&J#WAR5)!?(>i z)aB)g(hp~Ia&oSgH5ojlnzBx<+a(qAie)rLMAp1L#9VZ@Tsdku!r|DPMD9?uk6zZ^e{O$>IA2ila-(I~fOVji zSIXcC+ok<`#a-r)sDPoj;mELbgcl?JNrK{Wa2BM#EGS4wZEw(X({|A_tmSQM+`b45 zuYk(x%i^E87T15Kk3U`nsM9oeCt~bgY#o1p66}rm@mrXTGCw1MW8-@|JQPyr41lKh z0>7UabW^|7roh6e<*Dbv1Z#Ws_d8{aGa4@>PA<}GC6W_oV>5~CL@q9;QyokW*-A|%TCxex3S=S2;ACea^@LBKs+qNOiDD;sy9uN&-)ty% zJe_7VrYikXq4l>?#j+%AP4%w0+@H~w)<%bXxMoig z5PMSHJHlMTF#WS)NpF7X4{Eh9l0(T=1S0Y0N#SXtI!?HnZQWx!<|RHjTU8(nG1T)A zM5BF9TwWCuY!In9y zZA@76c*&(6=@RnX@}x*k#Su7c!!%y%(;QyGdy}^H7#X>ya(n`};KMH)LwxP%IIVd4 z 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 literal 113145 zcmeFZhd&asO%83Wfh4+R+$x%5Hd5fL$deCNcK1! z=X@Wp-tX&keZPOf?{@p$KHbiBdtcY}j`KRt@p#BWc^!HY0%* zQj6{>XMrns1VyfV{v7t%J@DhLV5Q%KMQmb4sf|T(gU>xzBquojP<|F}jZ%LV>y9so zT6Pez-)b|IDocBqzS|#>ArKV)pFh3N%~uF$X#f4AKm8HWRQ>l)e6ulfiu>O`S~kMS z@&Ej_Yzamr;(vYvGey9Eeni#&39-_Dek4PxnUM28KcauqhTz$MenjAD(f_{9|0j!< zL20C~Pmrn`wlY$dcY(hD{zMI%Tq+d<14Ex<<#mkW#apB}SuJ&Qf`%o7>>zx5-i(7AF-P99+KHb^h!PX6+KsiAPL&7q;m|%O?p_{Pq_k z*>Trh#E{EF#HtW+(k?aQrm48$O=rX?0{)-*@Pd9Q|+Pj&hMe% z@o{tPij)6Eb944+w(~g)?hi^YY<5U8b8v+9EfR_My#GEl^zP4V`kfgLJhO<1Ncmz; z@(=b%zAD&=!6F+{X~)sZz zw;u7Mk&sjWc&g|4!@ZsuKO)Nvv#G`iy3;Y5CwgBDBs+dNnk;=^t9?z);IJEyr4ESr zxvDz&<$;i{>>NG%gkJc=UAhfcC`$3ee!GjKEuk z9AlAw{r>%FuI}}0u}4RdwY3In{@FcM2RNPrt)Cso$PpSfi6!BR-3fmVBlCy6r%#`L zmYRAjw=bf&OO8TM0dtB-Inl!(K3765miXM5JDv2s!2n_kMou9iiYO+rW;?}$8&%ss zZyxoz(An8JSnYEzAR;dN8qI!xp&x@w{&D*cFAEAp(P!S9ypCGig45lm+Ntd5o@wK1VOyj~_qkY>U4-md!M9;KXtJ z1GQb42kOH_v+wf?RBqp%D;YR-$bY}Br@x;UFZ>EUvT)sv%pP2C99dpoc3E#?%6$DA zG0bDQe*OC1qMrZBbx)cCc-sj~m*+>@&Xe#w-2D8ccLxfZ%sj_JV`F1)RO4E)eu{qh zgNY-E=$D0z6RY?zMJxf_;g2IL;wPU9oIYKDJHhO6Fe!DjZ;Jcx+%#{8E}K)_86Av% ze;&auugAvt596W_Q%B$nBRd26zAd{ql`Ap(3w!>sxkqGbMex4LmXO$JYn_ zYB|Je_P7fw=1*R`ew|BEkz;6R=>k==oz5 zslRSy7TOR--7T{N)s8>Si;x5JP2-BOFh3$8G1c=|k$V4+%;bOe2D)-eNLw4yRgfy$= zGtuE?tAj-si8u*qSWceI8Nt-u z4>#5H>6>skzn**2QAnea#iO%JGg$+h7Wi$8jMiJnH#asKb&{o9ZGJ9qPrG$r;Qw4& z8UfdkvG~)cMkrUh7_(8YnWufx2hg107i?^}t}EhZ6jc#x7nh>)hnu#TL8LML@VA`= z2g{!}p~93M&+1=kK8>Bp=h|E3XP!vrV0V8h;&0Ha>Hq%yJARd}lg)FKi;$+UYNO4* z>=4uK|I$C#Fz@3hOy)EM;jpyHeS6R}+*I4m;<~G$3*v>A+~tbO%Z*3NT{07slZ6Orii?Yzp#0w) zExntt;4ITPI%?|Dm!o5?uOEvYOvldh_oWrTd86EQ8a93U@iCUhKHc*=3I#*=81Z{8 zit4PZ?P9gUueA9v^5`NJefo5jh|_PUIQ^-&Zp;h)td`M7yJOZjZY152I@tvE)CH<} zhIt_qK{%XxhOozvb1v*iremIvDRp#qG9-vuh&m2^QtM(y8jHIXZf;?G``G#CGN7(s zGOh8gc-yzw*q>(<#d6M(-l))ABr-$5+;_bRPQ&>LjBb2wnt-|YVmAEG`DCYP@ANw- zSy<*=*yX*hz^-7?B`2g2tNi`xZA@GbJo|dzrdCWiHI)$C$t`&`?cL&{Y=qjJg6J-8;f&P3E6jIDCxW37!p-%BD>!Y*6j zPj331_xwY@xw)x^So`_a{9S$6S@!OMTHN;A7zQHcuI_`KmE=w4h>}P^-l3h>ka%)i zk4iIE4vuu!5y@_O9zvQ_-Q2xAi$g8SP?e4Qt5uuPtn7Y!4IH`;Q@VfAaXg%jwGU0P z6cILBLspQ84s5n+sCRc{D3yLmI2 z^^;@uwxP?dTdFlH070hVKDp2a?7`oXSt{qQfNMJI%-TK^qX@e~K|%5NyyGx+bpd-$ z_#G#1#AT{Jbb4~qvayBZg7-Dtc@6R*00_l`h>0-cdXEOji_N-)g|~Y}F^{x~I30&e zF6F;{OXE~NMdEVrp0*$ML)rLg3oi<>l92!NnJO5EZGmKo6dc2kO(5_Sg{KNB(C zSYdSfw5dxIgF#ojKc?LRuG;9^Ut2@;2)e2`%&(}HXtp>fA3!K``5p%=WqLlp(aZH` zs8|Cxruiy4xoLRV1U?r4FR$U5EYnjA-F&|!1SfFYh5j$Z8ntAdJ_QC6U@|OiY-UPE z?6}Pq(84{Jeh3TkEUMD6?ELghR#CDxp9_?R=~y0(*%1^JM5<@%!=0U%OsBo9rPauG z-s2m9i?XQ8FNI@^ugeG;!B4DD;8rGbsx-#Emqm&`eiUC)`&~hg@Jcf5+PbA1%WhLx z>;;)tjZ}ITVmEm-qQlRgJ-cym_A0@Zwj{f>hx755sNY=C^o8cDT5T?7YiHNqG%~cX zxER}VQiz3J(a%&^KmaP1;@(&4+1+$bvS}#v!c5KSK7T6SwxBpb4VgYdEib;jPHWEw zl#)D(UiC;|z~K0}C_K@JjgCC%ftr1PX6OC;_kv7j(C7~RYJJ&#FmnmNr1%!G z2OW~#+87Kl6;VRE;#D4oM!3UMe~(rmIRym|V>MckBalYGv>l5NN=i#xi)-pHReXb1 znVOnP%OOS{R`bo5+JV*<&eWo~ zThZO>AErs1frop`2(4zIFx?|LJ`bu9&-_4cx}S+C&Cd2V{D>iWfSH+@>l@+T+CYG_ z6~-sc5$wSP9&TcS@Qvf8GzV~a&EWWL=UF_J+i?aK@)=teH3#)PnoLO^DiZg&A2679 z{7xpOH=%}JQiCp=yMRD5o)e`@RcVh~Z#^IQ(B9tOpy#(iH|jBR-{4Oza3*(8&&;eW zA|?x8mqr`7vqu3nFtf5YLIpp!vIE;lI)TUSuD{cJL=L>J0gh<|R7AS&3%jg{!a${t^>-@(+#~}cCJa10c1lKScS;Mt-jUKhfCa7t zP(_67Eg99GTpyH9J_anC9qF*QtBB**BTU>ouU71{>$tVElK~$H>TGMth?|?+T&f>` z;jT=Qd11nY(c&j7Dq31zi>!Q?rFXgY)#JSA5Ctwi={trIRzW) z-7(-Y-FOrQ!7WTRYs4ui0s9`N5CV&4V4koy`89aWOP-eF0Py>%=`SI5jl)+`5uH{O!3+V_JgYQ%Wwm01QC1g&l;5zgUWg z-z})HZSFjt)p8mopsrJVzWl~ycQ?BBnJ@#u|WgO}pw;Wc<-}uI{7R9Z zT~At{rMPAP`|AtK%TY=GB}#3t^Nb3kzbJpR&rRiXqCA(hRXq<|*Er%-%eG$BYb&5- z_kDfc#ogT<3CDRFSGe-RG6sF+gpbX`7?h+e$OhVBJm-L^TW36*4Jj$<`Uj^+6t&nn zF&AjBnFR&9qBMj7BP%2b<*{Q{&}}8zEl&SI>h%2g4dl0f7@&Gjj6c@KcPo>l={fIZ z%Tkj!eT!@D7P#XB<~|=XipTs8mo0dhDbb7gE8QPgGJ@U~`Mt?tR97hS$NS}*RZ360 zxVpM><4nmA_0+U~fI*ysBrkJX|WTP4Y% zTza4gyU#V@n)s)od-^RWmp><|`mjwEv+zRU-K%G+LDIX!P|mp5e6A+&dY<9eDd)O7 zQYth=vX|A`pY@~}Ts1X)0)>vOTM;i0jO1v=5%pJxp3q&oy`DG&A>M-pAVl_{`bw?r z093Xb`|{vzVPOjZs%TPnFH2pU^pykdmtLDOj2+U!>fCc>a9W|uH2J1g&=1`h}soAP51jKA)~))KPu!`+bUIzT@rO4Jn^}@1`bsEOIgomMxp%@h z2XA}1E%@Tai~4T3*;>z%^-vWq%pu##s(5nLkm|d~AV;3+UEcPBCQhK8Z}#cYfd}R@ zP%fk{@Cb+=^(oOKLqkU`GrX8v|BO}sQW#|RSRH?wlLHl(zv&Jh`Xd1XjK+TN&`+&J zJPu0S&!0cT%h+U`k-EkoxVE;o@-#bXqdr2Pcw}j`${WQB#=^?Vezn_5{ z7#=2vt^l|k6lDJ^?v%yr_(OlZMMpXcB|$}Txe&HhNt#jC!^p_k*7O}jbe+n>?{6-m zk|&P>DzeHTlT5XH#J&m>B_sG>{x}UP@wgkpjF?9rP;`=#`a?37f>5KBa}_17@*SU9S*>v(LbZ3unG!zVfD_*aew?_c+BBoivkI=4pduu?`n3m zIHAJ4eHn*>FSA%J*0r(454V|4DlTzT@+W0|#hK*Jjgt$-f>*k?%upqEdfy-9ei^Sd zPH-N&fRM_lYiEgI)zz{H->vNe;hzSqa75fiC64?ofP;bc$zW>Tn{+lHeTh}A)tBh7 zWzqHd<9_+;9(4htR=!qGky#LWj$>wK#&x6_IvLw$4ao86|4(pA(f7ntb$R$uURymH zb9pbnTG9aAWCH9_t6VrR0|3@eSDhPN|>FEi^PpMJr~X zzb#fkNuo@uE?~E55M5vOp4{>WSdA*z^rhhs0c?UmI|T)$8ARgSTie?@6&IkwJUusF zhsyG4X=yjA%@F|+5w+{r8G^n}K3S#!sbv&o9s`x!k(Fi!BU6He_R#0gk3-8lOUog& zlCc+|=WG4bhKHM5>r_|+*D4hjgbq4bxsCfHWlk;G3Faps1P8G=mJNs)1Cr>lbI01h1y!w)o}2WZ38idWhRp#Jg!}^xgvJseG&VG6C|pBba^g@%Ek_ z;jWkrqHuM7E!ScBzDT(3dTI4Whd5qp9NzmOTz z#`MOidi!U1jL-6iGR{bDhr4&}MqLsGUVyKe6@=<|#c6y_^sdnOX1B&%gTTq}5S|j!V zxQ4&5h4PayaJt~;t08p&f}VhGWDOU65Ue+pwYTk7g1>U*%9VimdE0#BB0>=9WmZc1 zoZAF*IpGX}MC9E#!^FTa^)5FpsP$GoK-ge7DEEdw5x;ox0zKyI=rO!m=J<4P5Jbmm zKt4P`7ty7%2EWL-)PX@)@z5P`8%ae)1^T|ITq#=^;|5k85>Q2TRSMNZi|!4bK|8mQ zVSe3wXL8Y<9&RjrfRKKNrd4oQ>??N(=+x@LA|VE51JoOn(yR{di>4x`RnJnKc@4Ek z0Oq2t;-#orq+6FPDQb`CoExKGccEYsZ7lTL7Gi#?j)f2XvU?GnuLcdpef<=F9L7~z ze`ET-6sl4d-5-%A3RXrdwec5sL20M)C-7nAF|%>{cXbx)~W6gy1CXjqlblZ5N@e zrt8A4snof1GZ#7bX(FSd^ubI6LHo_yw`Ay&c!EM0etD?Twg0*i*ZK1-{&4cG|1?q} ziU&j8C|3X0T@5?q3#>#P4mMm7<_DxpC`UyUzE!F&f|<$vLNoMj*|;|a9!TC?`UF%N z@Hy%RYIe?EGc?Sou4Y@U-erfj>jJLaRL#Mk29!Yywty;8Utm`0+@r?y)w*aBm>?Mu z;a{-%=wQbRq_xPWH%&a}>OmmuFEHjf7;O0nPeK+Xp8J$9eyuqDkP=1c`i6#&;Uok2 zfYmz&u$sJPGj&y9M;=5~MO5BHS09WZ5b4jYHM2NrC%J%K9SHq$s`s*3Xv37!-Md2I zJ=Ne3S8bsDNH7J}K&AKyQUGfId~0h{v9aNS`|1o`Q{!G?D!k48JNEWpsr~mZqL%_7 zq}T44XHQ>W@Y%aRCr2i5(jLDD12;A{WUJ@J{MMtu!SVv$oFU47OuOUWBe1QVNA8y? z=k~n;<^wlm50)*a+Gn?IrEv309R8E-AAy(OG-*m zC$MbHg9YA(*3D=Hh2WK*tIZ%mlL2G^$^_QZD0FGBoguq9xA$X?dV9;?m$&!8KYg#4q z7?e4*cB3viP+_96u`%N!YvMmuo4RN@j=Yatg@Xmx^aQGk3<5@684iW|d*s1`2L^w@ zFg>I~>mKYzAczwgd3hA5SOLBZ29j`?Q7^S$FFnXC2|K+($izwMJp+7Y;4dqw;tbxdM1Zz zZU6e5BAiVT!SE9qp0^P;haSp!L-z@wJ(i@WM?*rjGKNMM=*!oz#7 z`}mx%0U?_Q9uGQ+5}2D*Y;qxB=pl40(x|L=I_ByLxT7c{kdT)bF1)lG%z@>cp0`kS zyInTo0wqqsy8~4?%PXbyPyZ)TBybeHZ=>#gI)gQj&U<@%i%UrnC3ikXxg}bYQ5Kh| z%~u-sj;wGX3O(qMI)VO(igA%nkCtybP)CIe*tpQq{9n-}9i{)ImBM@fH{tZZd9D8q zx&8ktvUj4N9ih$U(5Ii;!~jnKjS+;aEpKxtPN)G|MjigDs>5h}QBaG92=EFKApyLg zrNfJvk_4)WEDhM~rD0lV^pV^W$HU#LkSY+FF&xa9@q<5-8x%`;A)NH&$}~jqL*W@@ z$~2shM$w;ts*X`4QGxf#_|bsXP>q*^oMlFNL`Jw0XTTMKQx@yThzMPgC+>L7z$;%= z@&}erkfCWysVA72aDh@Zq3J?PWTiD27j!cpkxAO3rDrG8;iJ>$i>vaZJi-N$%UEe~ zJS}ZDJH#~anAhJ_;0vqm>CuO<3WLDsN~&&6QA4hz5iW zs|lDMVn!JyCG>wqGkVYmK{)^|Tg}n2z&BKepP%14JTC3x@TD$GaV2^+0A27x5NHS4aT3*(_b}a<@B4iL-cR$=^Q*)`Ijf%=Qh~_6FR99Dr zq~VlDB|HLfJuVBb&&I+AgjRqZK>(X{mdSZ~+2oqZm)ftEiJux+|E_4yXy-Y+TDv*A zG)s^V3%5NL$!#ji1guY+udn1~49KA=9>ewm!ouc<#2jg{W|WINcifeRa2C(Y-D3BdjjaBWJl($>{6kA;_#yOI#sMu~`W0 zhQMdcY;6*Gz*Hh0dTJPKO5`O6j2FQ4k3h;~13(}I0AUFV2$0i@9v+{ui8hB^*u6z7 z${24Rb_06ig^LZwi5!hDugea8&StJK?2A8u6@PfhTsCqHY!BE!dL||wF)?b};)jMa z3H6h+Z1Y)p4U{41(eCTy#}l}TA&+g~h-rw6^2hKvY705GCV47AzmKYBSpW>GUX7JH#Za$IEk!|hv|P-Qth;tPAPpyX506JZRX_3lh5Mf zf|WQCco5J8EZ98cQpHc&m1WtNC<&Nx%~QF-1H`|ZPsX2GXG9t#;7ALGB?r*-NX2?Q zj8oBfauPGSc@s6mtiiV1uu%yLPp=h^{_=B5Rx#b&NtFz<;7VZTL{K~8M>w=kd+p_d zbF&=(`vH3GqrS-GCI-ZKXYjj9K7X#iC*59lo|Ou&M0huEX^3VaT_RcD)$jd_?gk!- zHk=TH&d?T5$0poC_rGllJ!jm*qD}z$;)1Qb+FM-80`R}iU1VmB9^GKsO$;(moNC@s z^G@;fKKfp_HTig(s(whzOzeo-W#LxKj??&Om6 za8as@Cjv;RSW!wkOE`H8eM`3ns6_;c;~NsP*rzcuHov-3jXzov04>W2d3SE<$X>t2 zsG9@kX#x#%*aaWT+?UDgQ%fqsLdAMMB7m=5IayDfP=?#YN(Qc?9m90}5iW5TUhfTt z>DF3)v=UuAGl6A#+DlvqT5)`QJg1_ffAhf^Sn(#b3aZ`1JOkxw3V0vtpFl81|H_rM z!WIO--77PGm;LJ9!82UqK|!V*Kd;$N@tjpNHocYVUCD_aOE8t-LW2Sa6u_0U#N@*! zRS0}uK?X0hs2#Ugz&PH|i;Qg#O?xwX zdsjOx#kGg5q65(sdWkK(t8~dVgt7$+a8fiJs@re>sT;9SAD5OK9*)uJ(-&n*1hnAA zDnx4Cz#~H9j-<9kXS~DR_r+cu(5=+l3+e@rpDN_Sg$raP!Ek#w9)0@sDMKMaH#hEL z8a+w1d7-b*9)tDgDA2%TP2e2=$e7)f#MA2M0CW{N(&T`V@x#i%2mR>1?EsR2j(0qj zUbU^N*-ifqQhCx0fw~9z>;*OlvB`9@<)M-gtrQS=R_I7dNI*$NRlnkqSy{<~%!)%# zu{x8)&CY+76CytFC>txi{Z@ZFj8+b2RKAfgfdoTz<3NtZV_1N#U*x$1)l+wsz5 z10Mr4EQFfBzuhtMQ*duDWS6i5z^^c{!0UdmNN5-+*+QHKfWD4RN^~3H}@td z$F}VYug|OCy(W&ajqBPUHlCy@S+uZ_?YAiIy-|617Dxz0(7**w@)C_9h4%w80Q?e-*M@~IkZG=N=#t+lkQUK%ay&AJrWB|viBIEwG&DX zm}iW)qkn7^IrN`~5~t@)xwe3R_|XRcnw%#s`Rh!l%){BS2xYzJZ_DAFz_mm*i|~wa zupi6E98s}GM@I(|kg-SJblOHSPxFbLJm&lHwL2$Gz{G08kuN=WZvCwcvdMZlii9qa zI=3cR<#*Ar%2MYl=4@O8Xov`a$2wPz4Su>!k#CrXW!5LcZLaIHo>$2D`O!{|jM%yA zF2A~&nf{;Hy*luQ(1Mtf!U|1Pg`)nVBDl?zwVyw6;c^B;&{Xx^l`p zPa@E*z`o2i<)ZSZMBAWvEtcshML;Z6O8wK;aKv=rh=FAfgf^^UDtvH*E4)tgH6lxO zK8Qd}MOjRRfLc{wbALI!`PT_mrvne7s*4WPx5-m=Ns~KCfItCLRiYuHq^53w$0#jj zV2>fC3cE-Z!WebCS!rS2YZkwoL(o+m&Qv9NwDEK;+%k1#28n#hMwh?>k>YP+b1`WcE|;MYm2OMTb~`93!pBb z@u?mcTsalT6mN@eP#f#|e641Q_>n6sztXAURQ7U1AM4f5|J$`GDJeVN&)H;@?AAjfxpN+1lj^1wmbXl*O5eH zB5!AB8aS>XDm>;S+vuNyrkbdo6W$VAKy#T(k6w)|2q_#8nqc<}mAPJ!K}Sp5Gb)gP z&$0HnLITLe9(AGYt))dcJSy2rOG_h7PoPhd_{mEA_7O&YRedFag^S{o$^w(2G#f34 ztZ~G?nF}jkM{0`v)ME0aGke0J@6t0e5+>eRhr{MvVJhRkK(pn20kkp_Qc^&6R#NJ? z!DvRZ3+yqzmF^D`(JCl#;glTy-Gw9KX2s<25bpxfbIV!k3oYB8;z+vu!{c!L-5fEA zLaDmcnXQDGt!E_oxI!$yQ&fvba_wG9{N(!U(eI)+>|1Q!6e`DUPrUEEC!GoL#PQhf zEzsN+P%3KTpWh~^hU%h(u*63)Qpb$Ux4cUhq zcn%I(s_t(`!&MM^bLUVLEW*S=N4^tNDjk9YD`yE0-C!cPL;)>)3WfgEI zr13)mj|1p!3lu+h?%WcU8I%piiabuN_9$P$==X3YeauNC(XGkJ?gojLv&~ZQp))ZV%h)uB17mJ zT?qi2|90c{@FwdB@03e-oL3+&<#53b@GJylCvg z+Pc&i!ZS0ot#Oehz6;_-)XrxXj*-mDwLe=HK7z2m_la(*y=2ScyX}2}m5LNzpqJ5* zhe9K#EE{=>YQMe;;FV#>T|7KI8fR1~LLlC+FwrRY1cd}eMQ9mQdzp`A(p@C(8oIhvVCTHB$LQD+i%-WHRKX!)-3f>|YXN5*R@G(p8!af#yfm*m=fhhf z7|EdjVmDij!vE5z_}DEhllltb>*4P7NOXHoLJhd81T_HkCsy#kb5mT&8AVL8rUgp* z&89O1A|p#~0#$=+m4PNV0Pp@o8X&|2lTiF&U*V23KaJIcQi+(U!^6Xt(#dn;klN1Z5)P*)BUTOo9O;zsGujF*ZLg9{Fk+*oc9Sm6 zX**E%Z;QgGk~&=l&1Y{DM-dub=nKi6|Off=QpIejL$zD0K$BCD<#{SAy{#p`d-Xa>V+ zfa*C3*#p$LXB0C}`6#jQBbD%NFWud^lV6Q;`@k%)M17_zF9}usMv$6;I#O{cJc*5^ z1qJb2;CI_%wPP+z^OSMJqFh_7?p?&c=ODIOb!1M5 zUJb%QuL}#Q!AjBgY7cwmwKM<@b{M4EQ5u<_PYE>g)-58m9#gT^!<+v0sAMJkV0gEY zhW}7lo`!^w04O~|SIh>qA7yv9DMfxMG9r>pn;iPy=xiEK*2@?eU&#QmTQ}EDtGxwg ztYTABpTc&$joLhYslV@o3jcw7M4pxi;fGVuFDu8WD#xN>pa9}(px&07iUKLCTi(_k zvg)!fQoTSWewIc{k~2$bVfO&aaco@Nk<1>M`-Vh-`QP`N;3#r;D3wanEp$5k0q$!7 zJk&hGSLW*_&kj@#L-fnF;yX-*WM57ImMrx!_-Yy9+YYNUl49>w3I~8f)-SpfB0#JE zxd^DeVJR-dOJjTcwwk=IS2>*;ErbR(_N9=V6>+BfA}0ayi}c;XQ8WZmG}U7@;!U8o zT)mO?l6vvN;S2+B z)w34xb+VHhVFKq}@FC%%Goj@I*SZ(2%{K5p&1W8jdjC3X9fG&MB=O;SgPeX7>g zx3;!AFvc(~mc_cCdFZ*AoxnGForYFWjA6qF_-5BDsq=bIO@M74oPmmHes}b{|R$Oq&rW86i0Z1!_q`gllRljH4NK zj=|JmLp}aYmlcomKrOk)KRfil_X^Wdjdy!FGl;ZGu}smwRJ9oAYkxFi6VRir71UZ;6}sv=2dx)=aa)@f z0BkTj&FG9w`m9JSzg$Bkr^wf|A?yIzwU4)2kHa;F5`|u45C;H2OgTfXvM%a4O{0bH zA`CfLc6{HR0e^m+?NOIPZ7H1CN{U7Z_s4vysE z<<^S6*5M!fwwmO%p}$x}GqwerKn|-(0hi(^W8PdQIBmcsjcffb{Ps8>5J4BuN#;O> zv6#8yL!?Sqf8-+^zJ{p)utDKu!EFaE0a_9aG7{BJQ0MjulGfjmJk7T%&VQkMb~`Dn zDL0!q`>Fa&iI}sL)xCR^sNagHQhGu*w;W=?f5V-Sbg}~Ru_WO=M$D9tX;Ray!+#ha z%Nt#_XF%IP5wWkVvgf_??mWRWe&hWBPBQ%gUjjZtQ$Ih2jm=F01Y$GbLjmlRah)Y2 zQhwF|gT5g{_oBU0)|}yj!lR{k^D7R3sAT*#Ev;=p1$i?WTP@h!M;-p}Knlws3h&>L zfXUj!gWXIp)6sl!q?vcMIi2$5v6HOl2#zMSs`XTSuKRBvuWMuy6{KN@o9$igr^Wf? zbDuScO~h>WMfM~ruYu##HU9B~-$T1v4DuQhFtDuV>3Qz7kdWOYELdIOrnTYmFbw?_ zMim0Uj-2s=a6ibPOf3r$;qkFl7_pRL3{M}$GY34bzwv*b6ee?iY``V$5ftH=lA?3( zeT`@?a*dyL25cM|83~P_$dWq%Xbl>k2FeJIt}Caz466a-(=_2;z^8%YSaO#fBF}_& zV&q$Ud({4`Y@sa(U>g-54FLAD2hpCV6r$xwdxDsTl@%A5U~4ebbtHd17y4+ zy;-5PUJ;0omuSgY(y+Hpk+gpqZ%%X`JUleGQ6EYHuvVU(8tOER5~KD$INCt=Q7;vu z!VVw*AJB4XS4p6H{?5u-BqzT~Qb9o>Z^j&)`|^d1s2prQBy7-$OPA&oc9yX3sOh*4 z3HE7--Y2(wiwK{NbHs=}A7b3f8d&zIv??C@SImaC-*tdZDEOuG>cnO`;Gn) zjAaU0a7AzP^8L$J=yUFJmKX~ooU1uZ5$@TniGwFZ%^|+Xr?8pSJqZIy4dDKFgE)UF zAsR5*y_T~OjQa9L4oZ#n_EJCk%iHHvzyd`pHfU2puid*6MMQAs0_*?X0{UFo0%)x0 zU4nT>QfPO1GxoQSF{kQ=I2f$=&Sq)0B`ybjU55>V5)T5oD2M=1&i~Q0=fosn_KPaS zFz>7_XUeGVaX}i$l0oHsc$j$YSV-?lVHgl{uuK?M<(p76M{_P{hyi+lpsPH0#*o$k zmdR22S9V$&I|{MDg@^nYv}s_a@Peq;hT{j2^H9ADM#&yZiHV8LcWAbm{%}Yto@Z1qnq9Dw}*#ULI20VYaeN*a*6c}T#n{#cwTLj+^ zP+=*M$|1NZj+elzHDJ&AgUZ&a4_pR@eNj;m#l{lC z`H?hL0|PpAhEkB*Ds5zL4cz^R9*y(gfK(aI>aB&JxRV zs65;mu@YzgXwyRFyXrF$H*yB9s|&;<-+&AU@#()&O8Gw!M^aN$BX+Eqdnu^M!Oq?c zW5Ey6>D@l_326L(C)^=P0;$d>$iB@r*2r+T87IBO*M~Ck508xW!0ue?-h??r_-YzWexcESD4$Rrth~IKVa!gfdh0m+`W*QJ0Lf6K7FJi& zH{6tI)*vd&jz)ff)&#@!IhqiItT@d65g>4bW*{C%cTf6euQ@;M?P%=||Ea9{tcg{W zQvnsyH!$Eyk2$UbJjS}{H8gQJ?-xN~9a(t{;a4CdkROCEj|jtJvG&WPR~`Pd5P+E^ zq5Gqx-~GXZrv43DT_K}@J}WvJT5i;wEFQW#PtL8Apk)-m&%(;EKFHy%Z$eX7QQ9Qn zZVPW!2L}-XnGo9pF$6^~zI)I;46gx*3N4#xLlV2<+jn>PfYS(igd#sxB`z|Y)&wzR>OLI3@~BQqM&tY6{lK>*Y# zY`vkL%7_xJhskzO!_w-ER8^Bs8*EyDC_-BM&ky_qWZtL6>434gePqmWH-7s_b`a;L zg~R235O_B^Hq#BEUDK=On~j6X4CNO5xGOhrvOIV*fcf5bQv7|I6T>Lc9wf}st~2JC zP*`$9_+`ma`Xo+yY*tX00)gTq4|+d;Mk@C9dc~a>C8njXDt0t1Mst&+uefJTP`ynV zZ#@{o}yZuBlM~<>@sH2NzlYGVQp=d`v7Kq-|Z#(_u zAYO2zkPdtwh&VNwDAe1}k$*JrWVFma9U#Z{v(SQCnFdYw05t-m3Rpa5$vHpuizds} z74o&Tc^W^=FIuvC(z{g)?%s6^s;dHPZRV5s@e?7+tm-$E$@=g9mhtH$yp{A6%qVz4 z9|1ZCIWstG>UZzvRpDZ{#yh*ZqW67bO;k=@(_amjuc9L z$R~)S5~({5rl(#WY0m18?15#_c--YG{GO0xYazZ5HE0Tdvo>o}Tv^&8A^Uc5m-G9f z^xAKh!*9LEGBcP5zx<5o8(^rn{QeL3w?>o25LyF9h!O%Q9!i{?wT19~2ss}!vJ0ZHk_DP2z+Y}8R&+8{y2tbfS&ORB=v6IM+GM+N#H^P)$BfaKu4P` zH(&cMnnN)fzIP_Yd+8l&jKZ#*l@R3>$LqhRB?`pE(1Wo^YhC6G2l1PcIly^3KVGdB zMjB~Q%)D{xHXF%eFp-02FW;`E=Iq?rz1MM0JK9rJKIIZrafi<5}tS+?ZV*hMxOyUSdLhB7&iV%HB2|B>Ps78ag)s>j<(s}2|S z{Mv-#C?M?!hHE``mp~AIjFQq4Djw+48}}Weg<@-&<`sM8lxcDpGLrBD?83;^<|wFg zK<|NiSa-fU`>nfMug&WRWdIm*Fya6|_;JW}a^vk8$~nTH@_tVNa{&hq-^!b8pv>Dg7DXQaOg^jeD~%L+~=vXr%WR%cP8s zd6*5HJk&$29NQ@IK@5JzM7X~YVNas@VsO1hf&jnjmbr#smOPcTm19at>{?XJFzE9A z2$7y;;8@s$b`hDf&&;7+_a53chEg!0##u}ZI94;zgZ?(OwMk_eRw@`4hN-^OxN%D^~Kg?-0!oNs`{$H2%_O@QT~Ay zdQUF)@27h-qkW)tOzTV!e@>}08qPb)j7#5jC#|eU|6~X~DPNLuG z0|OaLvMW29s_~~`v1vr`p$0xApkj+z;dst=3;;4J3XGN*xhDQHVyAfy$-0z7X*}WPWGX z=up~)p$HX-JmIs=_I;jVjcI~vTCCD`e9=fmE|pzeuID^?)tb8EPJeZDCGIfO;E#0aHT>EHlbCPbV=3Zg{_C@Ha*tkYff) z+&^pq)jU+rPT0LuxlCY8ABe|fayWPT@YvN8+X}rW#Q`6JuLhJ> zXBtH9<1rYg_emQTr-UgRo3Xj_B6Eso1QPcmS%JNiEU>g5$ zI4X^!vlf9{fR?~^_4*&H& zEu6tkZi;{o|D*_FB`qH`^z!qDtjBL=U@*?Z_PL#MWV|Na0|B%|1fr?1qMVZdL-J&o{h#=CQhJJTz#I#LHlCM-t0?u)-yu7nxNQ(Y!|R3?t?S8)z@| zQ`89obsDm@dERi=REb3(WeW`j?%Xvaqi(M=`o&11AU`%gUl@`lui?vW+CcDcw@nm?<&J^aG&vCkH$NOSEzWic-q7wf7o3k>uMDt5O;`n})9_*M~WtJ;Uc z-c`)k-U2a60^ccYVBuM=%77%{&oEI0#J>dTR9a4s90&@$olc2w$Ys^aXTAr+KY4Rdqz=9H3t%7F9KA!~WH4mPe&y2)(W)fFf^LZDAiL%vT#?nOiC#TA0R#GxlOUgXDm z_mE%Z>w=nA9`8P79jHv7E!ZJKAdc5zaKc4NiJpCTh;^{S*$~hq3Lt#kxe{gf*eb;xby`Debb>Hv3UHdwZ^Ef`!L9rY0=Fx>8(C6TP^FVub)K@6!(+al@sAh zzB}Dk+u9FyN>bm5rpmjZ@#hOQZqt6wognFYKmOi1srBU7vXwTRbQDnx=0$n13$u>* z*jWtf7dLfE@s5jg(G5H~NfkVbDrl}z9?|*y`8hCin{Ngs{>;nVPJ7z-jkrv}dc3$B zc0)?;@SY4>#>(B4mxc&;$Fmgl9OT^u@&<*h7<)N7B4^rD@kVLAgAcgzsh)RkE3F|u z<-v-97$t*>&Qw|?zZB=zTYw9Tf$ti`9ij!tidD+ieyYVQ0tkKAX^EajWpkkr2S znNL2@#{0$sqyQ~M0onyl^dF^M2kwr-jg)TKm^2>hwZ9@H#SoXh8q@}}6UHnO2w_8y z1!dCX;YPDf@n`TtV)~p@10vI&*=T7qb;P7(g~W5GLoU9eP!e;yM|_lzIBSSGA>;bU z(-zM=+aL?s@q2jmh*-|J$gV5LeW`HWvt?%#jEq4h?YLyzuiwr#0Ae$`?%(gHj_(I@ z1FbS-J?HM+Ss;`oGf=umCwqXo*HTW;Mxd>&ExNBU??hzY8+&Mm9sk z&_Ce?q!$pzKib)^YAZUblnWE{FFq0+GKe|(O+#e;H9@)3%OZJdhcUhd=StpjI#5(9Spubz}YXikTnA1Nx7+0qjfKuo?_hHKSuM zj0GBs@tmAzi2p8KzU(_8S@e8Z>y4F!vh5;e>eoyp5jFeV5XJ4z;nWzdL6tAb++-kE zBEE6UmgIlLLM|$x;NX{hv?(4V(fs?7M>IQ@yks)(e(~JzX3gzhfhorC)fkmOL0}X8 zz}rwwE!nG>VJ!bKdvf=ST~eyQM#iUX0}OXcJ<`Qdms!H_U$3*{wL1TRex$gWv1Hnm z>J40kr&j=OMrOgeix>T#HFkz`nO&jlXllk{kR{oHxQ;yJ)XLwRI?I|*cjvSS&1n{jpJr?h(HGkEjfdj4nO(MD zcQKoRRJ#(co)hVewA}vELe2sGn-nwu!i6%PY(NSIz|U(2p8vyQd!plZ0PRq=m|EgG z0@F9(Iul=Cxo1~hxh`~MK3#TEhxypx{ucF2OGG!GsM={h+$gpxgqygwAeWIqKv{77 zimqprr8U>6OQPp{y$ca~;+qW;%ywrmI$NTQk9%9pcAPeDAs32^5_LirT!#(Bz$j`? zw{Qc;QQBb72vq+{+qfV z&PplSLbG02wR@R>o9eDBZi`AN{^QTo7)3dZGTDur>6whOnO~_gHi4A-pC-#r&q6{hvZ&Nb5)j!p|VSqAbS^7*w93Ci3Ch zoQP|YM}R}%r}-X!FJkYDp*^N9`sBa7WvIfKk>be9-obF2IKt3RSc8- zxR>#1cWf1K5TrQsNM#-mFy9*^0Y}(c?kFIZ)o_{}gj#_RABSCOZM!I>{E-_Q?Zo=^ zM+4q%Xwjk+G|U1UiDsT;x1u?t-P@7^itY33+x%dla7$w#H0NPR9u=TiCGU&U+d?R| zv>mjU<$=P4a>=cz5FtsRFi66%mH^JeBv~K85k!j*2NRK9pt#FL3b$O3opV#v@oVgB zE!uaH*R;$C8n5L~DCsW1831BAZ@tPsrkLyO%G>~P6wo~IqmK6@!s-;hHPvWQ<&qn( z(qZ)g$0W64g)jos(1VFASWxq>Hl9$ANPW1SEv>Jw|Bfqf4(qn*C-tFR^kqipS_d}< z@qPS%BHWXPSKgl)+0pm#_>#j%P9?w;vLgE=nNBEKKz%w>s{H6E$Tzl!8w1<|Mtt-- zdQD-vi%E1WFN>tdCWG>uY)9k|BS?r?Ua&2357=I2-MBM zfINZeeyw8Yy$u^&L?B*wcPfv?@;R4(@9#YM!@TuB+0;9@4P^A(!0nUVW(YweU=6K@ zTOJPEGkRYP%2`Mr{uJ~8lSflsVJ zq)va%=3)n3gvPwMy<3i?j3A7-_t3)a8ROp?f$<}N45UF{Ui{)3l7Bjxktjcf_q{z} zHYwJm;sd~UIflP^{%i}H(B+sC{e7S>zB(Z7)#g>qQVm5zXIGa80phM)NsAJ9t}rV8 zG^Me7d|q6l5FG)WBn?{0rGgg)4qQBN`M(yIIMked88@7Zch75cuDB@n^;Z<-u5QYR z|2z@iw}mDA|DU(d+(b2G$7PN%)|9|2#%U4FQ62uP87At_gB7N9%6_df zXB(*cFsQGb8R&Cb865#SRhie|K2R%;cRsp*T3HD45F%w?u)qj^OPz^h`BSDEA@^+$ zJD)0Mwsvi}w*|5Y4t(76TLPfa#kKOUXi0RL`ytKIz)e1E?%!2A^>S3dsJ%uppuoJ# zD=H?1=77kcW&FI}1Gg_IR;NX;5Gs2*@M<(-7Kl^)$gGrc8ia)BEz(hkgT@n3xp8L@ zPzMeIuoY>Fcl~JO_-5Kd;M65O*4aNWy{GJ8g7o2zTdbQPKJ#%cGPSn4^hxJ`z%Z|pjyiKg z^pyNz!Z_cltRz}_;JZZsj>s13!}t~Oh#f&2BBxp{1N!xq+s3%joOPl(lc~c`f%*MH zc|=7#GdoL+{L*XEdm;kL=+Fe_mX-!PY^p53#&+b624!AjlA9hiLqg%6rHG1)pDLM` z0xc?XtHob1NqigeE0tfy{8a25^>KX4y|ix9Y4}^H?AgX3#Je`#Z~>O zEec)IX!h3#xvR_O+l)1@V90Qd_e?kMSv)V!2+(y5`is4L%U#sCRqvWDT;T|&bo9iT zGpqW(mH%92t~sE;cPytYFG1)TkL3sQhmbB)K?UP4w3hS4wCNkIR7Kd*#ZNkThW^Wgpq_V&jw3_?3Jz^K%C7ZP`&LRCfCq6R5D1Dcut?{OzW3b`(qlru+f}*MK&}YxjX?JDUBsZi$s}; z$kd@dI#7<`17dNB0B6&1nMr`~6L_SWTB9IVfU6s%a_XxWg`V!$@gsY4si7IRWh|Um z7}ums%>5gmF$24PQ5B^RwHH8*3uO`97);tWF45NGJ>Y!pZN|}H$%S9{Q2V>rMq8^2 ztz^DfeEr>Yaguw>+238!-Yi!j3`42UgU%GR?QWgKz;~S2E-6=wiiOq`&FER5aaLAy z{yAG%w}9@nj1w@u>KDc8_HHHUC;)nyhJ{U){U+&l8GfvZd-hl0y=J0F3;@Z-vH3bl zGT1TCAhM-CN%g*V&O3gaEaDuhnO>p)u5Z2xA5n*dfB#rk^Tnn0C5-H#^v9APz8k5* z@j}N0q#)D2a_60=?|(~Vc5aVOE{n{?B~1dj2#c7DgbA}emE+3QXxm`%JiHn1wK}F> z{KbLo=?~Cf{O*nk{V217Df(qp6YOvFw&b@qy@jsTTstPEHtWX-7KUeS+8n!Aaol(B zb+hja6d?uy!(m`=-*x3`XlzFf*vFgHZZ?UTqyScfxgWNhaMGPhH`DuES;A`%%>|1F zeP}%bDHBN%?f5c|m=DUJIqvI{%!q#N`L|xJzWkfd#uEn{s^1-vvN`c<@^}fu$;}3) z_+03jEuob=-Q2`cs@lNZq%_usyyMObp{cnzI0zAWr>!j$yZ|8coi5u3J1=FoI?K8! z#rP(LrVrSz|J(eLF&{M%Xwo4mO~#r=y`DeoNfTXsXBO$vRgsUD-6Abvb+d-lsAl`U&M! zE_w_T4!N%h!*c+a_;y;;|6M@Q{3(M(V>Q1joUBCxZSuBPH(T~TG#0oJI+oL&!5CP( z;Q7y=+PEEvJRG-@%=ENUafeU2b7{zkGrkUL^=;*i@VV9-#MkB}I-R%hnCbh;)NZRNM z9hLX{t3(=x_s`+m@lAF9Jq2MEH_2I>9raa=yW-EMuW{%{6mabLJYpjM-LQ9^G4(xE zHxx-BLwyg_oJ8MwXZY$GOhCZyg3(S|g}p|a6%=xuuXjCG4o-ewIW{?=k^`sLr{Heon05~ ztU?`1ea3^J=jw)|3yE+9h(9Jo560{a+0{TUO!TN$uO#Gzl!YnUK$Ts+C|%PRP1Hg_ z%6JR$!hOiDmYy4L^mB@9`_GvhjNYVps~raHVIM!v(b>Yfcz@x-A6IPblpi;&-Qbq% zSFQ73U{K=$UF9-*!8+PbfX^GdO+2@4DlsV%pwBlHs4q}qQZ_#&N%A>GH%Fv~%zou(2K_0i+y?88tUqCFWA}N6kzNwPiae|e#_VtW zy7M$OH9;+~klbgIBm~vn(lK2$mES(-7u#H_KKW#7$8`)BxM!fKM^>)Y#`-EEQ2QTk zo61#yPv*tbr`S<{A>o!+Q91eN-24YE1~@0oBDZ5t>P69i;Kz@O%N6feW(zU7AKtR(jBJFkYRPjh$Q_6Y|MqPsy`iPI{Ztj! z-V^FA(C^obVPZ81JfcOV-~2BX#^8i*K-BX2TTkHEFSgCEU;bu1#~URJ-NTrVSU^j| z=^bqDv+K4E=`ioYeF^#FS@qrJe_M#ZBnVVs>k^%g;fcht8k~l-j0fKV1fr7b9Rd8~ zC!Ze#>vYsra(X&!Ma2CNWz!97cBpyjW+dq|`joG@ov)3*b@gx<171CX*8Y{W9L~ut zLqm94gF0T#A9<-fsQ?{ov84*NRGs}a9*BYvR&K<9!e$5N2gV!-Q0wmvhn%0@qM(CW?Go^9 z5;X%9KIp|Y+VV5&BePI>awbogUY_!PWcTTw*UZOlJ;}LI+6NQ0kXvq{QqAO z=J8|S5dRfx^sR)U<%ZQAJ2%PEyDsTgshGc_Znzr%wo{~JXGAY-^qgxDn8xG|`4YUL z?9%!E@0+6ZayFzdYpsvan^ad|m>0JIwvO%!$lkU2j{9uKeM@CKs2Qg2$@Oa{)idE4 zL(~Ylqr&i$Z0*nt0%?PF^n4zBxOVq`1{Fre)?dS_SA+7Kg0F z>Y8f58VJZ;t@t&4-1iM`1!8G}M1bI;_jE4$aGCvOa*Va~7u)G5#NA3V3*2+@rOJsS znpwW{tK)3<2hoG8H7=Oi9S{-Wa(q!Q{DCc63|it#k4;?a$_#uV!KWXacbn=;@!qTNiIN>!L9tN=f zGhpW-B%*L@fA!e{9>a}FLO`q5Jt|8oSkkqeX8udV>H?as2KkpS2genzGmG&R=G-38 zPlQK%?+<4wZ_imp$VPwYXcY6-PhYsdr<=w5zLcP$vJe+g5v3AwZ9rq&W~#~CGdQ?b z={xLHTy#yveEEDx|ByCT`)gwO!pPW&Pdbe?FWlR0gF3ZW6@l+F%9^DK}&3ly4}k=FqpTOaLGXvI?mk za6u~0F}mEP^OZMsh$f%vR)v9P`|1N+S6-T;5y9s!3UURMkfp(Wrl2Yy)VUeMYhzrB zL9@t~N^20^HUi*!2*^}G@z00Tr^GU6e?@0<(cgjEuYl$r)8~NxX;{?{H;sfez8?9! zcEg;u-MU)NktT))jJ8R&(7Or)GZC{A0HI;aL<$KS!_@EfQK^CDQPK6W3bB1 zb{m_!wtx1TfvSgn`I*ZYBws_mYM#`%I8BLa=RS$}{_%jT-{07ltT4z)=i2C?f*=dt zvB&k**4A$pMK{LpZ+ret*2wVdl`m26jrE_E=446sN=htVuB8qiVWHS*k<>)_;(} zdT<%nHEl^wNtT0KVyF2vSWK3!9FfeIuX*!4A^O~JwNtBCXNOH)I;1ZVj3YbT4c8BJ z3xWIi99cK~bmrzwePse$%f3@dohnS;KhpPUg+!107f|vIx7pmUxSeV2GlVY1rBP1m zv{IKdod%*QA7Ozp61k|=a5GMn`hz0e#b>oHgW;1>Ny!cDtNvTpH4c0f`L3~Je%}A^ zx3Mv)zH^>zcX;a(2f+dOM-a}tBZJfmBCE}fpW6n*g$|a zmT3zMqdYQqe&Cj{Mz*J~N*5XSOozzMW9iJ9J-3JJAw<<=Vu52His6?j%)2vJ6^UiX zuvXhWzWi=PiYUfmgH^xdD*dv=hFP3Oy?0}_E=if)KOU;volUbeR!~Uiq!TIuJ50zT zG6dpXTrHjHFb36DDXVrVO5@|$=OXK*2sMm-arN~ggV$LIcYi|=A4(#Y>1q7ykNUv^ z=Yv*#|8@JGNxap~cixjvM3&&MyT#Z$FHuWP?fO~e8@<&Z zAhb7aqg5iV$ef&#@L}6Kqy7a4mEVfe!(G2WMfgD|Yes?qgqvDDOiJub5KbWApNy!t zRclT+Me#M5G~q=|TuS&T0vD^02%Dj~venkHHSJQdF_A~+EjFxP#d7Zf_eO{9osH!F zTm1ImyICMCyzCdnx1>8VoAR=V>4x%>NW!8b^U{gM0zovZbC(-RyG_u|u)sk&{H9<2 zj)B2Kw>|G&nbjPIR}pr|A3S=82GAJ-DN+;+j_oerc%E*beVpbL>Rdm4D)R-CWg>zZ z>P?1_FT-|DG#MUE#$@t5_lOGNnBI7W$IES$Sb8Vtox62l)%4<9QmqTwFS$`iR`^Xt z=wXJ!v+;mvaa=F#q881%X}y6&L5Ta&ayE<5%7++LUvIzlTE!Ep$@&6~LRVvs=-lOz z8@@fEH0yru`#KSR{LI3cd``YL7yl_S4K+17x=ND!38#SFer+3n8HU2@t9A#rYeA9s z?~kk5!BOjN`Ickls$0~{+x)|2u|~8bJd5i;TJt1}hw~fB=e`(c(XyqozS@6(@W7Ce z!uW!%6`uAgHSIgcQ16D#8nEH<-yu_*6w1~{+zkHY$JY- zFTd^TO*D`!ObBL)#dV8dNyruO9B;jPsiL0f<3k;KuShNMm8YDGpH(DpFfP~%Du`IM zh9`(st4;e``P#>4(*0x@^{Z5dW`}IetPtciWHJ=B=AQ#nFt*C9WYc{nQSKsf&cQou zMW6}6|$*l$zd z&1klhG*({50=lW!=k*3<6|;hTg?h>Ykr0bpqon-x&TJ4(Il0-Q{4}F;dVj#w*L1Vy zs5JJ!Uq&WVx%&9Wfr@pbL4J9Z_9-D=f15z0hZ0vrxXgxP_G+Qty3}qHB0+~o2-7Vr z&{)|BVe?m&3qF+z&TdlW*1!|^^8awMtn+hP8)3dWoEpM((&tr?VfPGj@i_s5cWi(D zi`zi?LzP*d=UEFL!d6bDKrETz^J}!lc4|?_Uui1A68zfoS-6d-);#$V zmaarC4UxB(Ucxdo5e|_)KDS+syIrkXLilV1?ETks#C7sye|s{^Or^9-NTt7|%H=?a9nb|MMWUw-&ij zmUY|)hD(&I+hQD`1Ot%)LIP^S`IT>TEC#p8v`#6(lyjk@=$Q&qeJzx$KgB-@-AA!e zyN?LDLyKU+qIEd%zr8-9UrYL#a(%{n#2V7MvkqiLWMW{5g@i|dR70op-#0U>6+~N$ zY@3_Ww5j6x6{pnER4<)o%5tLlV)^A<)HtY2@Ky>23fl~q2f7PVaXyqOBjSV9Q{yxM zowPjbU3$hQHpVz9ME#972kRny9a1({W(X!ZjP(RHnk3dvU&wxb_0XTAN#+p$1}(~d z2hAap&E1SygIZEf$88Vjz#XwPh#fM2q}{n{a%lzEwcM6tIVuC~DxT%egL{G|IO(6_ ztz@22nvISHU4!G_aF3d3^|ZeAZn--CdxoINFmjSpq}Hs*1IHQ*Q#4ER_SrJHri+|3 zTfQ3|b13xsL&X7gBVS})$k-hoDGNMxWq~8IbCiL_gJ{B9E%&~LqcB=DEnM4vR^fA) z#&m(c)6%%ymt{$29x(kqd7+Z;OtYQ|qz;!+zM1Eu^sckUCd`)$!A3jWA_>zmR2`DAeo7Y5)M1oVs=1T-VBIrvDDi z%S!qRjA+&)M9*q`BmEK~!Co>oPoH{;lP6k#`p1qY+glYU5?tvfHVgAWrjQO8SyRA~ z)0e(mSAO?GFMrYk`Hu}tvag26-%28iZZy0=uSgWqtC5W%r#1%i`E4ts8r`Vo!#K`X2lgbr7E_Wo(ik02IC7TQA5b$>@ zxb=C@YgR{Q)^msf`8gAb^g1ylfgBEyd$8vPi!oPJYiOYtJ7jOf5(7;kf#5ne=##iU z&_&IBSK%mK3$BH8 zkPH(D4<_A#h%00-FG)oHvkC=_0{%n9-4Er+PUL)hV8z+tqh}J*(i7fyqf%p?$K0g) z7+ga2GcODKQF_TMHnXbZQ;%X>+1TW!6DM)FG5^;S;V=v4kl^b+MZc#LGidS`#dd=B zhIU%YO?hLg^X(;zm^bLEznet(BMEW@v`lVwLQ4iMUx=qiqycw9oPYfM8RBB=8sF`H z?&1;&c|X^bY(1o?X~FuK$Qy_Sc1y%JL>$pcgaQ)#ktbk^T?UxM2KU@0K0zMcQ7Yui z>qOvhL?Ctdt{7MYvX3H;M66?HqrLZM;{v6^&GZx;WH2J0*dTdWu&zv-**cIos#&Wo z(YCyvz95qrKx0Go#DX{hVdR=oxg83txU7rm{NM*5Il|o!eS3h{NRs9YR_(67fb(qI zQ86*oBk+=Jj3$ZqNd17U{9531a`JN#47509?YF^azz*`6l&j4%^56V-`T)80@ul)H z(QI-FW`+Ju<^E64pAq++#K&W}RH_jxzZPW#A~SdVS|qP*$BvR|7qUWk6fmvqXgXh8 zguJ~A|6iRpJZ;wy5s$4+2GMQnpW-y9PHkADUj8#9u|(8*1;an_*>gkh*>$ci%*T8L zhU+f>P^qpqUU=8AMrKR$2gz(<<1cd5s(wZ}@6Gl+@>5O-7f3=^L~DvN_8729n3DYOu^z&NXa(l&3vk@POS*;S z^roo9vb818Ay{vo3I;RjaVQu!()XkeWnKIaW z|IJaDT3K0HiTJjaC4;;EwpnDEG#bl3k`ayw`DInn{5CZoCw{GL{l&?45OpQxlp)wH62VekO+mNZJNcUwFlblG0$Nok+Jj<-DWsADIp!i6CH32#-l+3Xtk{^I2Ce2%0U5Y7zmC>?I8tyMXbaoEH_y=e<^bLd>e1JgC17(S_=Hi&^&^)HdhF}Xir%d z;)gq*U(h;Od;h?1;(8^U<6a|7cs)? z3;*bSBG?cZhWW0g#!@^Xe38UON3S*+Q1CtCu`jPo>!*NmIR|U;h3t?8pvt`7ZsLM- z)(fVQ_DMvxcR=@DPgs$B*)G?8iK4vEHBPvXztGwwZq8`um<5*Y4=n zpyc}tJ3lD4K&HD}ClYxCPqh2EDMF5sKo5uudZGQPCmWTDH{W{V)oHA`d3~U!RhT>_tdyKNDDoX4z?{5hF`$jWc2R9tq@=lAQRS%CVI+Lkk zWMo7;Y|OiEVv7_6P`Q7C)hU*}YcP;Bk?j^_vrzqBODWrD zmde$boWV1JMuM2b>f@D>QoYMdeR$KGV7AJ0>nR`yg}uGjR>{tn?KOh#dw0jHzj|B{&b3o^qaqdH zA?%Lf

xC`F5u39<^-fLTjOC!!C(BY#*xkpA3WRpE796)O*ld_f^)l>N}r*eZ+H$ zn{i9wuoSvRe2ry6*suz3sm0vjE%RO7*To}`XF&%pS=heg;bMd$M{Y!{7z^&^E}|zI z5fL>>Xm)lcHk%zEk*}(LbLUBwP8G^ZsL0;6+w~_5njC?`Rz$R%LJ3jkG`4%}TPL?= zpNYj?a*ooztt@r6d|MeWH4$)j|6U!F^PaHF=9bmvJ^HmsK>P`nRpnT<9JaHEg1rb$ zjlg=}YG`H>)-De7b|x~=(6J^t8b!8NziyQa0~Ag}P-(Dn!TnL8Ui?}(JYe-mzxduI z>*BbDPX8Z981L`?$uHSmrm~4A)6?T%8S}(~8w3SF#6=P<|0u)hF2|Z4Kklg8pFCi? z4%r%P2PFe4NAW9olsXFd|L1SINu@G%zD-=kr$G(AV){J!yA;w{%!U=Oq+q%Dq%48I zD?L2m)_&eUnPX9m1IRM)0NAqofsT-Je6BISiA}oDGUet4NB7OGcKj+@C=|^`C#y0s z|E>!8Ts?Vzay1JRe@-^aZw2(OWD-GUgUkMr@{Nm0)EL<@gw>Ld({d)ifA3w`^OFs~ z){2qa#92nxlr>_QnM?hAcI$rO!$1kCe#^72D?BQx#ExyB+M$ja z6-5g2Cv3oVnt1;wvjC}gh|?k~afz&8%a+9$7&95RY0gtSKv!_>cyq_TG{i%B2NM$@ zGWC(HM1`%Q_9~RDCtGiXGd(^&o^Zs!AekvF#O75+jFaopa5xwvTLanVp?g(C5J-qY}n1)#>L^GpDBG5ZCvR5rUXS z=sZ!zzw;!>TjsaZmjOvc)a>drK)5isOa9QE|Z@NLce{ z7tp`)vo3qj@$xUvgR%Fo&GczOA(=rY%9Z z+x-}9(jz;C;4Peko0OzIVnLf2);=ks5cwXsg3DbO3);!H6moV6>VPW=N1H^Ck;S9P z33xol)M=ciJ-&J}^xhVXHW1VJbf2o)lX`WE2kVNzK;H}Glx)L7<6H3K*uW9Q*A>By zBJ@^;q;H2*`gW;Y>DQtFLKZ1ZFt#55)HxgROb%^GtA3?w&%e@L+Xy*L+(n6dA9mi> zK?L&rn^7eX+zmWD@?JNnBcLC*9Q^+zyA;h2Y+tZ>alCqy>~p@GyShNXZ_l@@G`|GM zN5T2(E%61i8j9E6=Kuo^fVIRUqsfI0mQe)tgMp6?9z z3Bh#EH06#dX{CqIe*8(^T#LN*{8eJ+ogl+7WS;$|ix$uBQP9|>KZ&p)`xICVtKr%O zJ^5kiSNoG)5HPZp3*T#&xCH5(9o6T`{FK*ge+aUGPMkPFFkj7=(D8vci^WPyq6X=} z1$3XuUG_s2WCK^+sum;tX)#dKCSzy|&hJsCtd?)A90eo~xf~WEumHe&_&epFVk?{8 zW0L5I2bVI_zaPIp(gYCZKa_QTMQfZhn6ORdIG*pWsXm~~4Xybpywz$tM*9|T@gJ~2 z&P@{WqQprFYwN$Xa8mt=Q99@+BgsWy4utc5iPj5p@pv%hn!>0~ye; zjG`U7JG-{cqTP z`nF7f%Qh_8fUoQz#9=3uH(#sV(6Ws#=*+D4#LWZ0H1c&5Q23E0KuQOYC-@W~kkfM- z?C+QHzIVc=WHArpP0aC9iq86TE%WH)FG-Plk2GNp?Z9*Vo1ZJ2J3$!E6v= z#f|>>nXJ^|Gyju%vw8CwTa5zQuMWDKGt(GYQ;EcLhgFQN*Daq!rKZCs{hw_Zdmi~L zx4N(~lIKZCu|4Kx;Ac(=6Es~o%Ov;lR_A}1D{pDEoR)ZvEf;V;cAb6v=w~Z*(<+1# zL$(pd2*?DI;fbNB&dtp3?=>AYh*{V474`+84B4MndGBcH@3a=hV;BbG$?Nlu{u~8uPvQAOF>w zu&|Z?Vt@q9483UY9-V#z zKlRLkJ)hsSNa}tYeCKp;&UaHT(=|e$w=;*7C$ACyRGU97Vddsk8-F>;V|n3|D@U4G z49&uSX8(*l7ulPP8`@osj(vDdh?ExohmROnU&$~z!{MtY(taN4nNzCm8S1ww5f#ML zcQ!>i^IwKPbTXj#V94Gg*B1fh>I@q@5bs&o>OllN&^`sE<=wE zy9jhdO@aHcv?aq$YD+g?UCzFFUV4|?hDc;iU8zTJTz2)>9vxbehlt{1ZtW5unuERU z)otef0WLFV>u2@N`Mz=+oKc>GsKK0em9g31Uu*p|2?{+Rqsz!_IlhA9%!d8juD6_j zc(MtcgO{I<45Bu?eDf{O&S<|3ikkCon7GgKeDuoN$FBq;lcljIiS!6k=Oat zrNt6G{nR0pG;NsPY-Oj;)GM$-XoUu|nftNHYj#}E>+!0+ytmrz?Y`P09(E@aUffg=-)yD$)UNl@ zXD0Uu4L=AKLih6yr0 zcsc7QMNj&*9ZrL|p{Piq4?pX&w&~_HMuCF|u9l&jQ{J95Yh>99U@Y?A|G`^bUqI`CL@2EtBhO9O{ENAX}q*&tpR5m{W5}vk#N8Ht;%iyF78|g$; zRnvlv=Q&y-*W&@T`@gO=VHS<4*I7en=+XgmVNw25fYCl6Q3OFJeES4#tEh|9uU-T_ zs)2w=Q2&dIwC7xrqQb3zc^r)tLy}&#oMuzR8hTSFnd4_v&iDgy>!@!l@3kF%mn*nK zoaJqR=s~^Cr1ltzn^(*GJ}aB3nY^@DvgveW>AnyxO81m6Wvw1H$rYVVkUxQ{s>#sb zKe$NF+;wnfgZF6^Cb}Bk zr0*1qN1LaFz`U+@qYlseH)B@PPxKoLCpCIn{#w66z~ta5QMKhf(*t{ZqukCOGQFQL z{>Zyx=UrQ}x>QPOL2Iaq3Zg3dFf3_Hp`Y^EPvkTe(u zuMD=bYkKTfvJd2sF`jVK#vkJBclr?IGeAJl++Wn%?c>9Sv~24lySxvZj+&-+4YW9v zSgx~Ym2Qh-p^MO2Xx4{=DBHBr9bQoe5$~3EZodrE5wbJNoR!fE3p}42*Ayd47n586 z;8*2y=Fl(Rp5|4a29MKrma0!r_4i%uQK-#3(669>L0f~W7tU&8qf_*y7CNcVhh^5} zaIhFXdYC5E>n?H#%>q28lBbfYrnt=3Fyc1zOWu2`Irm%}`;C{}X9r8~-sQ$4holvy z0x`YTmDlXvRvMLd&8@a`pyto4m0**Q^zW2vox9$I)!jgf&HXx4cyKTukV04#iQ{rQ zkT-bR^!x>CZOmY__)J^;NxgR`B0FdcM?J1HwpIvVkT|u-;_=E`mtX|uHb_^W9?2dI z`#Cdv<@a?13EqM=vLf^cQ-@HY&YWLxVWGmus-1!JE17mGosjPV!$AnkDqED#lKy!W3lIXifbbBM2ySG zs>XNvXI)}9aQ1HvzNQ;BFLkCQD8pRtRH5A5&|wEkwkko){%3oT!lr&+_Snw`hb1L| zN&{8x)t(3Sd&B7HHR<&h1`B?vig_-eKN$2@6ctIFy|1~x7Sbx{m|@NMvrUGXpP!$Y zmbY);{*X8AlWs-v59bm&K|#80r7VBlK|JgNzTdyH@O>R{yw`UGCn{qgL`IYV_A)@U zc5GpM#+e;4Z+;qwP$_$_{jA^JZu#qI!*r0i&!G(xuleOu3kRP`9;V6D4oDlb=IYc0 zu_2u(D=SM``3lZjfQN{w?d08Dy`}Q<;GPAs^B%{L;jR0(LH=>xH*rV!f8UnXmUUh-TdAAmOR-5mWm19&C5v4dGw$Z6H`SP; z4IER_mQudHzQ_>2Z76PDzFzd$p;@k5vPJ`IIyAqBuf_-c64_$5M`xLa2KLA=zS#BY znB+xtL;K$((&X>b%)X0DvM-}JmX*FV$;fwTUtcdFC@Eokkvg)Kjk|RmE|_|tchHCt zfbQdh>mF>m84IU(%nLYv&OUmgl5e!~L8;z1A%14vM$hn{EJ7p9HsWiY=^K-Hq1{4A_~Xb(Tw`B!n;&;M{{@ZJCq?LZUkm2p!eB9UVcr=C zN10eWE*Dff&E?C_e`rt|;5M+hhP#o|bbFjv7qNz}wf zK>n~$rzHxE$hKQphCqDoh~LHPXRDX%9bXIeHkVK?Q30nE63@KL|0)IPGcD`8viBX4z>V(}T(<-yuL zM39#M+F(&|iRsu!eI^5LgBXK^GeVW^Y|UJLxjVCd=Bu5cu%~$~f+5hG;w+@KYpInb zv>tRZ+|bn;?K z3-Iot&Zy(hkiy-ydo%5Dey+piJcrA05S&iO_ddpHV6;?{O~R13?rQsaKQ`WLyW-Om zXcb$stSl{aQI9b_K_92!cJQJ?wb3H8=~L>m@~5LC*6+<#^=7+H+hOtKwyu73(d?$` z;BPI4Co~kdO>)=9`qWa`vJ#DZ0MH4*@4T*nHH@ncm-(H&y5|~jM2HLIGgDIWKSuM|C61Fv$y2VOq<^LG#*!Q4 z#b>GJgovZ({WFiv=1BY8DBivS|2p~(C{f7`@``tpjpC}fOH{MKoSlM-UC|b5>N3Z? zsMg)NFIbzc<{HUvG(2x+X<6*!aZ|iwNhANKtgqiI2e3!%zzE4+U%g~VBy8mg}c znQ<>TYN}=#9%KC8g!4gqjU9Dp1>$#j{ArTB?8{R9*v;-VYr%l@?3u$uZ*`o5hKL}l zs&Ld56&-zqN8G5w=L%AJejPTanTUtS1xi4U_X5xv9{oL| zz4w!y(R&AWV=d~2A#cIQZ3WK+4T=>hie-ASQtQzNUtL*R6^eLF$peq5_bHvoEd;Z*7$>?cuLtFY19M3<6QbA^s za`ncI8Q2iQF-aRSaSuwyIr>yNEaLsG;}Pu!YDAlv6jkKCS;HLez8w>gTBAN&UkZ^MF^GMn|!db(hhOD;H@QwV3t}pPn zqhvR&T(frSGj0XLee?~mit$ABG9&vV-lEV5D>BH|kgQevRK9qDHtI!4wH|?j!88~a z*^w+4Z11ck>{o2ExdiWtH5PwlD{sSxl|%2nEojy^IL(%u_T5dou3I7{?MT*$cO^|$ zh8%#cpRAb($So`q9Q>RPs z_O^Ol8Fn&E&J0ktuo2K)Ft;;63*oXvq0!vh3S!?2yD|k#&>KAnT8{O(Tq?&Lt)?ek z+Xd-1?fW6Ac3)M^qd%?olu7?zL!PMqJZI*6mlo8B&I6%*epEuqm6wJhB__~ycXI)yhBNmD`;k8#LoC!iE_c-S!$_8=x8Hlsg{=LGb#*LHvQ{3%0=U=V!^NnM6|=vFz224&hAnn37Rq5v4?>@K z2vs9%xW{rKEAMH_DrilyX^UfcF`i0_JG5ECkvDDT@xgM*TeBiytAVbrRitJn1Lp{D;(Hp}xTFuN8JG-UW zp^pT-06tm<)OW4;0RgZX&j$j1M6mBCZqYy$u1npC&W$f_Zd*7oFt8IZ!*rkitXF## zbF_ikT%#f3}311q>A-hhM#Zt6^T~Y56x~QzPXUW0~z)35lt4_E0pogqDT3q~s z>26nKkA&xtzJg>wr$IhLUEG#tmXO%8z0-3O#hJ~NWd(~=Jgy5!?e(Q+DgT5;rM0ds zhIND1I_>K#(hCALbWXl&MGFXyA3|)93j_>89=4B<&(5(A=Gfopfj1ug-?FHa1#L`O zF6Auz{Rb86xHJ0ux9a}>Y_Tp(JNSa#(r=|H2e>KxQEeH?<~DYn(ygdrpS#PssHa_B zf`fmOnII8%(dpLC|~?i9WRklzM0<^<@1 zosquP39-OrogK=uWLI?TwS+=OL9888_GeBl^1d2qbWC8^@g8%dTNE?BRhVvc{Epj^ zK5e4(^YEZSU1z;CJ#f~QlgYYM$UV=GzJG(%@N>ag|>yP%)-20 zR>tx_^ZHR!*r}1~^00r5eNfPIqUrb^R`)cXtIvnm|4P~eiW&C_)r%mddA~E(soZ9v zc7Ezqcn}+Ot!3@GHt7ROOwkgq1A~JEPXyZssZPNMGH7MyGTz7aX@g3HLM#_yR@}AK zgX1*EGt_PL|Y$z&7`!4ot+B3 zdmjw|;4mbpSzqpg@rY-Ca9RxIEwZdtwUgUm*^=z~RTBX$2j;a)o2Clhzg)EwId>$^ z4*SSZ&hWfBL~?*k<Mh?X7ADEx+WWqUfg-!Mqel-gM_TsUE4;@n+wk_5sbG{lfByW_ zyEj{&sh)aFR`){NHmaNQ@2Dn);q*%j$obAk3SEP-61wD#{!cw4S8N_{n1&3-&Fv}T zI>o*5_2{(`)<|k0B!dYlsYd$`UsSF(dUGssi}B5yRO3NQSx`oZ6hO-kq#3gd{2Fy* zW9o=42lwlE)%n_PS&Qp}^fqp=KA14D#D}8JwTXPwLcU%e#IT~bF&F^Gh-F9<4)OzhX52aB7diwpN=K{-v&W~y0wMmTw=>}xc1pq+ z*yN&)A;9IZSaJOAoPfxZjB8wMJ~y0Bw64`TmcKGRpsqbiHdUejdA6guJuASLKM+>5 zna717%K|Bux{+^OkXoT&HnwAP2PD@azYMYP0-!HKU2Nu`pn(>c#`iRZ*3twW(YoX5jw?j3u z3<{BSIP5~pILynNvPqj+OKv&LuSuaW3x?L?azOzGQ-?;c91MMNKE8_HC}Gp z|6%OC!?EoDKj8Da?3uknHX$pk$hb(zCRtgT*$q+RA~R(x$%qiyAu4;1j1tkXBasm@ zGM@LT@ArHB{&}9`>A3FupS$BeuIoHMUigK$-q%TVrE_r$VuHV|NU$R|&NYXhiN4jhx zKC^j9k>FkWNb*J9R9VToet)BMx{2f%VT;7pMrqK4O~~npI*|g`DMz@Stgau&(W5PB z?6jL3)bN9qFW2L{;K*%y(e>w#FHHJG`-oiyvS2H*bN_Ovn|!RGVLrV7E*W#AP$lD_ z5#P%l$* zTL6IEe;XfNm>KF{lIBaI2yvostyy)$O_6)6{_)K>OW?>6&IZ|?B;hSEa3iL^c+~P} zZCyVp2_QdW+IqbvX#75^%B+D&F^v+Gf!jScQ+ZE3wXgKT(c?oWnUj41xq65_0PhA; zTKOvq=6MP8@GGG-1`Q>YIKU0jZrsdvJ#E5a25k(KZV@fP@OEKKg$Y-`b6Oi74q}Zo zxv!s^2V*l}oC)mUIy0U>l5p#xhz=Rx{WW|d~@Zi4|^8mBkKaE2nHs-pTgjC zg_}$2pm0<3KOLN#s*Spwf3Zt^kz;)#6mEpO$%smk& z0Jf7%1Y$c9Kk6_c11{1vJ3k9o(P=cG0~#R4z?NDaxg3i@JnOe-Yhw299@|B1U>ut2 zpfu;5b;GZ|Up%ymlL2~At6{PQ^BEwa=>7xWA5ZZjM~GG|(4Dp7F%Sx7?GiN?_t)_criU4Lv4gR`vN-9BktcMILz+*Y3*+am>0m>g%o zimKx8PF@tt1CcTl6BF#n6_8(gZ0+jk>Vo)=Q1*#O@3_8>&cw0($zuqrEb-f#j96W1 zITCSZGnjy61s%&UKMuWKt4212Q$8f>c?lkwP?!~X`SP=z**zk)6AAoBH*CE1oN1X@g5&NKmS3It3*okRyiheC?Eh5TA+F8wRg5HX#&#-@?8gp<|9g2ap%z(=S>rPA*P%fJ~5 z289sT8Q8=-o(-!S%wv`Bd@jOf#3%Cg3Av|fS zp|?siP!$zzVuIWPdUECvDg>V&iuHAIP1@epK7EtJL-r^f3osCqGo^R7GX3V6B+cdA zjiPamj3-Yh$Z&9fNIeD_EmVDcB4&QpoisE})QrjQ%=masS;*crIW6WL$5N|DtTjZ(Lw7@wpjSK(5w9~FY-D~KLi!(&Vfq@?rU`Y z!%+u5&QOhKWMNUz42EVhL+fAo4`Z#*$N}3>|FP|8KS+~-#88%SRcN`pwW|`prN=yi zvl|xNBxsjmQF|Q}YqpoDcnNbmpC%#7>~g>&aD&2{1VPnhkiJzaxXV7_mzmS-d?TCM zw?wW|P77cnhn-NN0Rd3ASZ;QJG2m%JEdvE-To3O>-t)ogl#Ru?2g5HJm%CJ=7^1zY!9I_mE&GDy!648cG!KqShG_|Ql9LH&zLkU$&?9S)RyqFp9KL#;=#FNZd4 zUR5I{uI>46Sldm!NUVZk&} z3{w@@S=#d*`}xDwpS@j;0Ps=<#~7_Yk@b`HCm2}1(KNT_k&lBhJm5mq+SvlBa#^bF z!VmwsbTm~7SI_+7|fBO$+B2 z=9`qe0QI>G?lM1kr6F7jG;bKwUlarJz&$^Lh$FdbbSCg;7{SZa9hIuZ~ z>uKi?U4gYOGZft9Yxh`(Ns21H1VZ@5>^r12OZN|w{N=(J2w*EthjmT+e}Ef#&^!?DBcLy zNfYNTi^z5DX;I)R5wF4m+^-Tk*dVZUA(v+oZY!ZzUgOlz;KHr~Wj#fi1-y$3=EVnK ztEsi)ypWAKI`2>+L$_DWbo}C^R`SqLFd}Q>!TO**&ah&Cuj)dkn?2HgY`_qQvKz<*vUfN>(TcC`_RY^;ngv%dtiTY0 zoY3NC#k2s0=YB%GC+i4SGzKFS`1dUhHy7K6_QE+mJw2hOGEgX^H6*A146PMRnT47Y z9f-I3J~og6Qr|Uq(qKd19@RMrdu!?poS5!q+CAn#-BlXtvQWRJmu&%*rX;|(hd7$U zdPmO)Dk@d6N2LYSUteg9nC{ixC5_+L{m-v}pK(YM4Zp+DUb}83j8pl_DXy1(8ugMw z?L-#1Yer+S0(>nnqM~AA*|56u%=s8vC0~ZV*@%9@%%6Q>o6-ZLx2dS@_0R;l^0AvL z2w*0(QUNQ#6nGL+GBVm>mMfqLZ8`lw$iJeVT(^;D3Ga$z#ZT(If~ys-V0Zt$M?Yme zZm@)dTNgg&CkH(M@_=FsM0Q>itNS z1;>t@MyuNmVPRx$mKmL(1Q_U6`Q@{nOf3^<#D?(A9E(eEA#zQE{O6gXaPcLGpZV{0y+%!5qST+#*~c{Z2lQ2Ws;^R2=a9G22z;V8Wk!C{{BVN2cc#^!nL2GF zXoN{gMe)%?o+hY;s4R+U0Xj@;7B5fi?fhgexVX4Dm59sG8K~NIAPXc+mRT8N%=v^ zk}-$o3_ukLy}5w&;we&oYqFA5c5?c=aal0(EMH&ITvk zMMyC4%l9%sC%~wdnTdjeh6+{C&<-MevzPsZ?ty?q3{sF$zXenv5iR9;=mV25en9|I zga8WZ|6N)3NAV232$l_BL`d1FPN)xs1dz+1B?G%S|NHI)8eABj^lH*O0b^r)wLKBn zqa0wRzC()j6Y3>F_%7UWa3Vup1HAa+qUgQoXnyB?%!i?%)uN~r-}!R_iRgU;K9PUg z0)RPn1?Uf1xn~ZA@Lm4@}eI^Gy+0ylMtZRgoQIm5~_ia0pH3n$2^Zz}El66N?f2a_}L)2)z`^W=>}jHz(P zL9tM=?p8HyS&-ecfX@O(=ADIr? z1bB~w792H0R4NZ0je!&SZ-bT<7cD|Aq%l%m!QdPA?3W%176S|sPVCWh=|#2H@FS`* zxK?38z-CCde1QINkxrGVxE!jHM6R-`{9CIZNjfWubWuwLtBh#>=k5{}od84PQ5~s* z3&%?|;9;@z5y``F26E8v!w1$IaM-Z>;kwe$*Vi`%8Hy@Sg|r|X)fbE|+82SY#cYCx zMi0w~kN15JuvuTmndtvkyBf#G&ZOiZ6k&1KXf|$fzf6-C+~1uey{)r6 z_ggUx@QKf(311FXBWlEp~U$whTl^OB9h^t@}lFPFO!X)dxgq%{*mm5+5pP;A_x&RCLTvL zajRTLQZjgdKM<8Ze@9o9nuT7Xl)NN|%IY`{2~EdzhLSxt5MprijbH}g0MMSXG3tko zYW4%R60M?FS_=>zC_)pi6Fn8ZMIk|phpOiip~&KgZO1@Rl|nx}^7f{|b`Iq=oS!n<50sxDC z>k309fo{uCbxM|SyT+HI4lh3jeS`B72G*c!2|79*8{b@ZEDzCMHK%zA^DoLM z2(d0+UL*)mmaXpc+J_R4b6k9C0>I!j`J_!`-uO>brz&A`ulHD@HYz#bpEv+P3!2Ui zWeJS#Giobh6yj8>3og^=vzAj94OtHN3S&j@r;6!2;=}}RKO;M z#Pc$Pmh3HB&&^6mNnwGdht7JHDPeNcmYd%DB=cm(U6^wd@o3wwa;#uQ$kBO zy-NCuAYiJM3{)4#RN%{-2s47;#|I{vPJexU&F2{4K-Bt*tAyyp`zeT~4r{VS&Kk~8 z91G^+rrTD`d)e#>SPcgU2T;SdIN)r1$yJWeH*B;TV>;IqfnX*9eVP${O58Tc@wCXY zsL(=dftwMIl1^I43tk)V`zO1F5$f;|-WI$P1 zYisJ5X$fUzn7bVV&7}bYV=4#l%u*SjFfuwLj3mQR;-A4h^ZFKmeLmof2$`0Lp;V~d z8_3A5)!3l>&(6h8eSc)50gvQe$L;UQ7robdlGGPJ3sDcRCtc^Gi7R0U5GNN}3=wsb8u_YxXDK;RCWw*Ni{wx@BS|Fwd>KDk;9!}clgoA8@^cxmVWHf;T&bxp5Mz@tJhOaOQMGDtuh1!@PFG6U5e$dyOk!=X*md(JzgWEc0@EmIHb zp3q+I9r4>BQ&*Mv$YXQU*bwt$vm)-?;{tvLKoy}Gg)$d11gO7lMB7(@_gE zjlA0!FNW?1{GRE``2@P4)^nP7JplJaW%Dmy;Iy=&xH^(TFhY)d)fv6e%eYm-EiTkipvhq@#GydZ9i(kj%hUS~feLGmyb!K~bi%%=UO=?ycDRxkP198vdW~ z!6)aOgz^cJO`zMwm41pKoOCL-Pa~|I0`_Y*zd6VsVngG4zH3D_{u5SIAT*|5foKR= zynL+XQ^WoZ_A|GnolqTPPHf6am5IV|IWpL45Sbv9tPMK}1P^G{ z6Q2Ju;|T5wjoN`$m`QC1K%_+xP_Yzo0}C%!&HVZ6$F@9@v#`ZZtl!!T4|)_bL0fuK z4bl(PCCFXxb`LrLANMHE42CL@y;V?zLpI!Qc#*nPxqhULNo3aM>hi@4p-i?Q5(klY zPRuu0uCW~iNX^z%bc@n#!g(CS1nmb=KpoC3u}2Z_8jOGG?M{8S>NHtSd2(MT4C#I^Nl~fX8@$$+ZPpM; z@kiLlA(Qie1`kjfwfG5({~3rwN2gBaZVGp7@K%KGkbuEr&57|ZR^x!Et3cWN$HWLFmI9s0W1N^t!5?xLjq9cqIO+$#$SGZ zoO_jCtwZX*W&agpDZuK0vV{(Sp_5MfV1K1sdVkoQ^s&@St#gLbEEkmWYPYw(u};W! zFlQx?mX(HdFwQO5bzT608``vh=o4+Ut;8ZarpfpzNkrbjWj$PbF2o%aQe1mG`ocrO z1ro@A7Br!1)^R*zmyebf(bGos=T;oX_V(t5bIS^Cj9=0a;->;QcJQugSs-t|c_NW-EbHG01B}XlLkTLAQ3*iQvDCkFMJ%iluLBh5J*n+5C@Z`5S6ck1E0xz#@gqJT(mgpX1JM$ zf?+lSKC3VdPqJFLem@sSsfv{676Gq>iooo=EE z@`{hxG|!J$s{A}RzmOVY^83gR+B&9J`MzQ47~+6rnz|fv(jH%(X$-%SG3PX4D44b& z)8(IQAEw$r_!|&K^U=KEBkAK82g7QH43JZ)m#I`IPy>H+D*zL)FgNI3CZjd3?W#d6 z(Z*tdaQd^7?zUl06svnAA6>pJN0A$1o=E)mw59`i-a(<{9;cZXU$D?84T4Pgz~)g~ z=7$3na6{;c~VnG2Bq}eWg$LRX#Fjq=C6t5 z>Q_g2u=jo@rCrREYNDdoiy`RXyhKJfYChHR{XzU)b&!8U#vtSppENqq`c*Y9Tofcu zhYB+y?R*h$pCLAgE7LrUXLBQK1hHg;?NrE7wci_ z8l_-(A7V7gW)KjbJ*%(hq>kX_YXuz;%Iue$z3Sw0#lWB+_k}LL*5NOJuU+{Vucnf4 zr*s*`^SY^5z>*7kZ8=3Jz)2gmMKo)I0MN0FFf+mf?g^3(ba0Gwe@5lSGeo-DSr4+@ z2Z9P&0p|e;DA=L5ZO9OmFaJU$!P3O`FGk_Q$GJ zc_5t!I%C$t0{}E@2*31wx=2Dyr5c8#)h>XXEXJ7)?F)xx@*#&JWbaGzkC&%E!1cWp zJ=DvKLKV!F*mmHP*i6Z?`r>q$HimfS>M1C^L1PB`o$|6W2m%WSVjff&R~W%MZO&>b zK66|1VLMISb>2YoGIaZ1B?8Oc%Kw`R0|Dx?wLKoGg{fNMr`z?OW#{b0qT zrY{)De0azEQ1Yp4X}@*<5VVjO$U%LsbNBYn5Ub+2HI2-?+&99z>UuGV*ZPQ0f3N3^ z<=E?G53RjNc9DA-v5epbdG7)r15?v*FeJX9W@ll+8x>I2J(?<@PP&4=<58k=XR?sy zfvHP1#!>_l!AuiC55oOV4xA#ypWHU$pR}(=z1B4kAF7|a`SMSuMR9vP^%nZ0w^Id6O(cj ztRc`GeOOwrD!oHR*)jo1EL*=HHLz=MU4L!0_3^n<7@RJ^>P#nQ?#`rUzWx5t(!kI# zSUg~oLaP*z338s}L}W zyLg=C_4RiRLuDDR0ZV(EsNwf#vGCps9fXa8{!9%;0ftX8Wwc}0|D2LA(E67Wt zMSzXK=S-^gt+zU94NV8SWscO2v9_6S{uj{@nj5pN}l`f~V!!3!y~q zCn*NSuSW9^h6VS8lTU4pf2vv$a#K&==Aim47yef%E6nsnkIUYp(IZIe(VuskjD^joSnG84%j3idEwMPTGdx zAp4NX>r`_Dxn{D*1%AID<4UC4!q0?-hC_HHw!o?S(2m7`p=vho?VDQV&s?q*qoN}V z=~9Fqn7%O}!N0$v0dpPA6%rN%Rr-UbkQr6%qw!n73uZwXa%_Jk!l(btCQLixTe|%D z*B{*jCE#x+W#IByulS5uSyf9vcxdkIZS!Ee>s)P&i(Dil zOUIK*Ub`2UlQ`tV zAWen@>_|ohWx(!bot7{J+w5UyQZurM<72KMl4pbjj`t05e-Fh;O|}xYkmVLKUisk^ zfzyo-mJm)cb9Gz$c)jKg!__m77(D$CwzvL%5s%y!9FA^!I&kTmFjjqxBgQdK+JL@e zIZiuN2cxIIa9)<8QF8@&h5HXjey#d}W-9Tt5}?3u_}H*hFxv%MF_<6@NGn5;=qb7( zb4%3&z!^@a>nZMJ6H6saFCSxHIH$JF;@R*o|KQU|=Wr%=tIH-P_ymtBJ8L~`ap{3@kdqra$)PlspH;J{F znVIi8nxjdEqOQz$bq7c~hHHy$p@Pti?7cXL+XJnhlO0{B#Mjo6l2uLeAD)T zx@Y!C3_;eqO$`@qVi#d_8=Y}nr>RHu*KXi{U;1Pl6uq;y8NXEzE(54c;AuiWF}&&b zWBMSq80P(^AjQpV7i?ynAzX3fQ|b}*DEV>ED++vG1P1Y%6Wt|Dt$sXC0mH4 z>gv~BaKE;9_s%~Uc4c2CwY_RhpzWzSx|0p|%T?v^eH!8O#)6H(Ki;-Hsk*00qzbN> zrti#ZNIUCRI$c6BLg)utpfKXZ(m?7noc-Yrvfyc^Vf&BBa=e}c?7sjj(%jZEj2c3| zzTDA&-WXBZ*%5&$6OH|p+U{NSEuw&kgC+iR$fs0&J{F+aJK#K`jsArSFs#0j{Tcw%Pd zsX@&NF}op0ZpWw#6WL1i7Qvwn2zq1p13@8|kSVV-lxmX+1Qu3TZNK*uOjFl-w};hh z5d|cXRjL$^ydQI8s-TSxTsCF7K0p5co@3m4WlO}eqUT+!hI5N09~hy59ZZ5ghj(aB zALRoUtIi8t2JRBl`A`oA#5X*2M75oeWZSiE2{^>b$nWR3|1TF+Ambd$^U(aZ`ayA{ z1jE>!&iglyS!`b$|3R6dTo<{2oFA*B_l>ODv8hl8&alF3nY7Dh5i0$BpBfsB@yDlL0| zZ}l7Xu%8LZ4=36jnXUbqkM!8#r})i%QNzF&xvv?1#Y-!%-LmGt}dI9?S)W_zY&&WK}!4ke<zc-l;N&W(av~zczk8PpYLWb@dbV z1T;hW5_i|McWY`5V|fb6rFA1_YtR&P$ZQ99TGz4`Eg6ta<`RJ1seOO6VcW36vwBNJy#8=WWCpc);jPPO9cLA?udo3w`t}*s%r5?eF zpqa+o&Ia~o&0&8{MlAUWbO*Dz;(;fFVg%UMcYt_9-vU}6fJ#mrFKtB__ARvjgW>WK zf(`}TU+e4AfEVDHAF{_sXAU2g=*l*kb*SBnmYF}nNN9N%2mr`Vz|D0TO4cml&Xm0M zc0AErSK*gC8cl0SE&rI7q3Y^dV$XNK6%o0o^|Aqum@=cE)*#SpZpHy;1FlVgeEF{sUPlVR4 zS1*4o!7%tg9jo6YslB$f{+)Ai+%C$Gx_o1NGw4j%`&{9H>%TklgxHc^AoQFQQG<=8 zHa7T>D%-|W(IRYA16O9^x*X8S1J>4Ksa)~k9`I(b=GNq+=jP^WK8kv3hk1M7N~(T< z2MwJK27yO79Cwv&Q3N` zQ&BIPNm@K#r10Bcm%4>j+FiJ*9Mb)vGnr@s=rPb~!RJf0S47YE5CG*t?hj#P@0_l= zR7;NzlPUL1xhZqDuO~3k{nNZy ze>u~eur}#ZdxFM48||25j$pjjOW{)a?!S_umKv$bmsP7OHnE`VneH2Hh{@1eKY=h{Nz_ zjYW;;N{kQ*fjVliT!W3#U?CLnc~DCM7zl6)?rzR>out@Xg01eLSlce~fbL7e6GW64 ztq6%PFS)q_u0}^X_5CBADM1#e2}tw9WR<8JgpiX3v%A6gt#(UQ*j;AtqKo0=^e0Br zmoX+k8%p=wsWJY^TnqQZY~wl`6(v@D<1{mzs2|Kp*33*OsPg=CL0cG8ol;b!d~L-k zrIO3ZhqJ(I5pi*E92RQmD-9-~z1jZ}bXlPD(QbsM$bcDGTeNTjmrp`YbuW5u!HYyK zXG7W@V7+trC(;SbzhMsrKbTcT$gX)+--B5K`ThNsEq6=z9q2Hcb2q=R`zSwJ<++FH zyeBT7=z%d6ZXW;Op8=n5-FQTq%DVOJeCDhyC}3 zZxD^|!Nx~dM4g07W|2g~N)J(QP89V%o1QUH97%c!lcGiZ6gDF)OiV1 z=;Hm_)F?6c^r8YCXe7a%0`ru>!w0n+fHZ*iK`28=n|)KHZdAuU8`2gj9ycXGK-GAH z6`KJ3hZKbI6^rJR5r+6_mJ_8wL3H!xWdNzs-8(qXa9hg`xZ;i0>;sKo!n?Dfj8e(h zU$A|8)`ryomLx!^m5x!Q=Ba^G>rPxJ$bW!{f>h6@m+qar3?iBig-(s<4Ag3g$?VaNW`J0$E>G6{B`89XNFRw~orSNc>N8 z3I4aOmY!+9@=MgIw4;-HEUV)kt6c3gKk$SW_-#Ham1JR%C<2Pdcb?~yW5ET4SmZkp z3y`w}f+7Cf51=%y3mps!3h>7Yb_jDDYu;R|7IH>xYKsxY{!;&6<_|%_3p$CXuBX=< zRDnB(a8$kLmh^lOMk!_yM@ojFttU!RIpmK+UK-(>325e~PJrf!L4CnVp%HFw$eCAr zZmFen{^ExxU`m2x6JP)U7~^lqdECoh`B+Hd_qrwJeX}X3(6h3#l8z)WJts2T-SmVd zB%G_bIDWg%S}3`@=x+dY|MR^31m5r_fRBfA^{lzMc_&SL_s%fv3qJ#fFy-3%`-5|T zLZXZ=i3=!p*j*f>S$boad*aj<8{yoJ4?79SqmrMhdNB4;64D$tA}~yjQ0lSh2~{4; zIwG?lmKr}hE8el=qq-sQ`C9S!TEiP6c^8D3s%he{uuKMa3Ny1mcxRRPEp`6#2g>vcvbIrq+_0Q$5QmxW7;x zjXZ0+F1T{5gPkGi=$CuPtpZ0P?|fO;D(wPu5peI2AO-F>ogF`;yN;&<_5@o}Qu@!z z{-Bw(K!m^ui#vj1?&_bvaKq;vq6#f>CJz;`GC zCgeA7PD6=SvMqPKNStnUq2bi-`ZjxK(vV9k(x=pft!FhcyX3dbP4&lPkiRZ(@l%lE zQjj~F-YbijJFy$Ly?+I>TKV%S&t{Ub1yHsWxiV6lk`Whbu!fUaa^#y9R+t_*o`jpe zS(Q>HWWpfH?=b;G@*PI}LYu31pe`tep-g9?i)8PZ6!+4Zj{1asnsQU@55w7(BUGpR zG3gC!*srAbbVXwpd)jU<^tyd$wzspl$F{Vz$a_y9(y8yXTOK6;<+PSOcu5?r6jvx? z4wxdSiEPbfKME%R9pyvWSeYRv3LVh9D4Ld~ja!FFJlR}%P3>!nU`z!zBN84&*|m2$ z?nwKygA4_wXk{65ZsYpPjRw*L`Q(x>Nfm!f(QHK%m_DG7=ue#faEqSd_tsJ`pm28< z=8U~x4%v(I@?gg4JR2N1BQ^yxEI8b$Y%X!s>?k7;$>l>5g~kz)7o>bT2SQPHR94^X z#O$QqN~e-aJAyEbA6QlpEP@p0&!Rbutj`9dyHP>Q>xi< z5)wvTC!`dgAW3i>ts&7`xc{SRt%?7%U>P&+I~WWCDV7Zzhlwm==$ZZ z=X3$X4&AgugrV8_puOd(y4NbD`5D4?AfSR#fxUz5w6OqFYY8%QN^D+RR|a?x8d5rt z3PR##WyVRDhiED{I1PS2x^ny?(w=?5x%HhPuTCcN(@DFTD_aJ^)$PG@u`i$Q4dz$A z@ixCB=6li0XRrEGWXtV~`-)1x8m|d556Fn!ebi0BOFw7beamSj`H5@NjGOVTjG^LY zl`XFLi3aCrSS>g~gaF+&6*9_pp-H%Cvn{?#NnS>R0l*&u0s_=Ne3?oh+1&4EnZ46R zfxVYKIeqQD5_RRlFoCyTQi>V-XkoaP5_O$*G)!^u>iV#o5FoQuW0zapK20?dX6&2h zV$+^vOe_)aSp@Y@=&fVM3{MS&WGNG%Cv~K_) z^H3)+2@(SrgcJLuu&V86(jXQLvLGS*&n8*(l4j{Y*AtYDj=aI^I6RO7E_3^vs_MVzB9zRvB z;~0L%wmtJpFuwnul@rtLh&-Q-ZH<)m`8v7tWXTClH<-!N7 zKx+ZrkpvJ1h?8$^NTrdA>GgGDq1`)@rKZxleh}ip4DKcfJP6j#CGWlM`YXL9Nbxly zG0)npbCUd>Kcim(m0$S~26ktk5%I+gujan)kFR(&SpkIcevToz$%Y_0oZ44D^x(CNJ6@$;vHEHdRVXHkE3ptez9+~C$DSrLst1e7 zC$=T`9dB&}$0mS-kZlFMtF&&Z_N^yPUe>FnT06ReO{SB>hEH#Nq`G(QX>0S;)SiWv zm2-$<&s>W-?|61|$3Y1pBC)VO`9%L-?NcsnA7b@jynpK0!7oA$4MEvG^M?ND{b0%U zBljnn8=iq`qb%qmrlh`x^ow?t8?jb}C`Gb1QMjG=($`Y}M}qr4EaAHmH{LuR=4R?5 z#Mu!1G>W~7>V21QkGDX&Rxn6XK>9fKqOhd-%;r}ZZwaw9qd*e{{jCmafl)l9Ff9#I z$j*z`F&u0j?Ari5Wn5N;5|s%*$=^a&8kh)#7|0<9rDKoibbe_LPI_?BeH~ z@$0xjDHZek!KWrV`U#3U!UKLO#w;36Oc7{wI$E~mlbx$K4~w<7L=f-W0e-vl0_*)h z$~zfxc~Wh6YMawA0rP{56Wdq8Q3xoGJvdJxxDR|=0H8n?Vx_NnW@d}?{sz&yZ?)%+ zS*#nUN3rw!;ag0~`;RHZ+8E_48^}Ld8^w4yPN9237~K>9WNhr=lib6*C$lW^ZMJtl zSi&Edt)>2b`S4E)-=7HX<v?ecRr+_IySv*PQx!8{jTCu+F59RRW(#5;K8 zJcetLvXQH234swbpCnJ7eA0MJ9#Ed$UotRD%R=Gm$JZmKk0Z|iq*z@FPyS{bh6{$9 z2Of0^E8m&Zr^&r*;dt?*H3gS&4jx~UQDLiW?i9z`QkQ~Z^0hzw_T|6iXo!1$(JAKS&`}-q` zmw|v|S{sdG7Xd1U5(WH~SzsW^x*eQkfqypN(6KKaRoyPD4{P&&H}=VR$nz)o@l1>M z=W`(1LFDaObZoAD zXSKr_Dds-%_NM9dhc%IvrSJg5^-L4ZvsfwMfV?&5#BiN#tzQwHv!@Hk`*C9W{klUi zJhH0lM(@g%d)XjYTK&RaVA`qQ&dyuu+#!lU|IIOu9fuT-(YF$|Mg#p~D7 zmnR_BgbR2Wd$u3oO3OJ5d5r(8HN$+<0yqiRi|znn1^sO!6!&ZE6W@JC9~!L7doD#R9Ud3MMqtOH9?aL|saB;SqnIq4*I67tp9dM!#C}Rk-TVaEU8duxAZX;KEE4_^J?w zBRcQic+VZ|otb4%)H)`@j>$aAt5(Ot`m@a|GmwnQjqJ*%$#i$Lu+fWy94y%9B>$&o zZ33sK4oF_UOy8B2yRr5MEO8L#0#0T*zB=8$H>-_?$99vh-&FGJi#<|j8Pn50{&}h& zb{Tjh(Q={57Jp4^k+B%ZMG!|4)^N}sy>iPcgk7A8X?D(g3NHFI^rFX|EnsA3w<4o^ zKT|{)1^f$qU_%1z1@8xfw?SAGYT+zlP5%ebIe~5&7lE52S9^d4qP}kNLxpfPGKkxr24UDGO=Acc)hZ$@22{lDXO-+ zvn-H#?4omvV?_0zkw+Ul;-)O&&2Nu9UR_daYS8-nF7Lly42ZkD3mO8zT2aXb6emE{ z7Y?O*=UR<-^6XD8=-d0h&sbrb4wW7Kq`uju%$_J*|?P~^jdhb*6) z{-9MLB|%j;yt94@CZYJ6y1=Gb)=&V(u3txMgsdzKfGE<7uZz8?5B6siRnE&hKG>MZ z^!#XdKz(;agf`xN+nNbCehAvs0j z$sbQrQvsty5Ezu=GtyyowTmCY8$Z`;``C?+Pbn`iPl-7tB^3gZSPYC>n?0zHuc+liY439MT&}?pAgr!T?n*{`= zcv@Ohsm=Ob`_S{AbZp@^?VpsBV-t4YiBvErOz0Mslz8^0QNeHmtSO>Rk})Tt;MPJ> z`gx_f@E4$H&%AO0gc6}6W@~Gc z2Uy%xU~xiEzfJ{(8GQ z_*Y!t>_E%$)vXssARs;zOA$78y#ir$hv1eZJi(@Krx5Pd%^!o)e#PmSHci3#n`f># zk&V~CWjOud`lpmDA;k*7R-%FNR`pA-;}R?%es{Tgqh@aKHcVJm9lZXdVW`LpePo>f zLKXw|H*Foev*h_KF`DOmpycuTV50{iV@RWmv<5>D2-DXO()H%@uo8anHk9A8rJ{*z z5()|w&sDNc0-1A%?nUgk!6@fHhz)qJiM(%DuY9 zNS1eJw|2&lX=xuk))CMmjPhoGlyDfJdzb;?Df?Fb_)8Dsr;R5XClkgFRg)svB;s{p z=GimC29@jTXRVibmJW1?W?07p6TxTq3}!roUI-NVb`8>+xkM>*XO}#5C2!rOJy;%# zwjJnh@?n>cfdna1LQ_haa61*lkHo4qfpO~<1XFzxTE1ZAzjPVYxo^QmAfnJ1Z+1fJ zQb}(iQAo%Ajhb?H^e&1~S5u+$z-0W(ihwD2$H+T0i5Sl2wjp124&F07of4e*GZ!3x zzLY>cS~Xy=M6uKHL+0~`!uIcj9*08OGDLBM;1Ghwg-oU&>2FTy2PueXs+hkhn|(C- zd_2(R!;aUTIL)%t65mvL3bZi-Af-Pf70!vF!aAbkjo4QRN!ua_Ow_t=sIGRbp-E)t zN=`JLL;UWDTFX0jtiIycIpv7(dfobPRJyRhG9yTmZj(gX&%?P&m0fC945{d?GurCp3R%Is(MdC)ZNWdGt=aM=*qtLk>hQ9=ofUMEZXn0R5A)R@~3R_UVm z-|qcPHos(Tg9QCQjJoUiH{VjBj5c}GQSryuRq>>6QT5ZbHKrvW?5EA9wSF` z=~ki&?9tXlmlT8lS<11U!t1hv_i`^(;5|Bc=jGk8;fwbh57@bPuGirim<=26#1i9= z7`+d%Md~MxZt9FM8VQMqG%6C~%zxAl+GLDSwiO=tRh1j-p+ovgMl7nS%sk#b?3@4i zNA>UiF<@hH0~`HeB=M;@z?Bnmqx3=m2YY*4bo~n!=l2Y%m?2gqJ0dWxVtO6D+*aUy zsJyau_l+Ii)n-}hND%P?!1YOZ^1#w-AuikJ$_m_hF8R!6RlhY14Qpp^fq)2FyMN4p zXEAuGID@8G$3%}BOs047cAypl`&c^=|n%P3pk^63vGo0Vrt4a$}iv@Y{6HTCal zED5AS$@x9pY1~cQ`5taw%i<#XWRu8nOdU~ie#e+?J0Q1iX6CPiKh(<^*gyT{0pFLR_k;N2@!`)4O<4yaeH!JY_2ZyAhy8`E+v(Tg+& zZ}NvsMk;X)J@0YQ?458m_F;2!xE@ za|Q;^U+?U2;^aIff~;_aVR!&eWdJN2d9B?Z_dQ-?VA@{JFUG}65KO=608AO1z6cJ$ zf85ND8}YJY7J7PgivHIw@F#R@y8UO>c=;d8;%X$9awJZI(y99*8P}16(`Y0R51U7Q zpRha$R(Z?y>*$o}X3^wCNZ{>D!+vGY#&?G#8*Yh`Kgrg2O0yUq1H7QVqU=2_*J_%q z<~on9egA&V*JI*C)kiU$jFYyCX=j~$kK)=EnLMaeEvG2GI5b9e4MH&A7AKx0v~*R5 z9wA@p%naRQ{U6uqs2%8jAR!8pIJMq{{%7ow_}5yG4W;tWv%=Y91GIN-?Q6g$mnb@P zgrau;3OakEx1_z%&i>}YwQj=!x=GZ0BFg7fW``U|QLl@AyKt$p8ool)w!i-i+ZFDy zzG2t?+vWb4bGs=nDVNnh4R_=_ zD1f}gcKT!(&O;Pat68)-KBD^YPm-C$y6WADAm)>40*{@3h0Ru^ual|)S?{*T-;9u1 z2{x>Pt&z^_ZP5hG)Bmol$ow;!_W_m-G&3zUPkL5Rn2#~o^p3h!?&}*vN z;3Xp)!P9xB0!ll`sDiU0kjpa~ztTtY*;8+# zg`$2Z8#x1Ek|AKQ>|AKVA}Nhemvyn6PBpb&dKULio~mgewPTfwo4_G<=)MJ3aTT8~LY*Xu&ovzkdhvx@`pu zOqpqE8^8hslgNavlIZ)`)fGzbmkH6D{eCucZna~}ZPO~`LY}@|ES|3&NT&{}c`1wV z?yF(ypghJL)lD@nK34j>Xe}R5y2Z&T@dy~nxwtnx87lPokC5*+3504rY>53tB|@W$ ze7U=O!|Sda9<3{*BYW?BT=UL12=+{!D%bY7-FWq4%>;Q;H#IR-7|<>#7f{${HlPPN`o1I|`sbrsQ+2QUHzJ0mVZkHOcsT_SZJ zdy#sAyN4yy8gd13UA>Q6eA4p#y(gyErfW&cMj5{~c7wDHPUitqi2s_RFX|)~w6*;_ ztQjT6UvTD)BrZMz9^_nNp0(Jvv_QFt_}(ge0~JkNrf>X3c&)(QE)PHx(`|u|r4_8x zOcc$02)S&ZCzIJU>)&Z4Dn+vwFB~r@RRY;Vd5u)+|EICXL}(92{_^tjpm@2%SO#_% z%rOcRflYEi9Ss$uy99cHV8piLk*yhqJ-tI-+Ecz6eLK)hKuZnEE?Bkonp(~)(yyLcAc>;1MZnv z@7#1_AVW*}(5IHRBCf`^63unYi6X;;avn412l(L{0gIliyiRl5RobnB??pTU^FM!v zR%$D>B|x@~4I+RoB7cY&yhjI8zthetnbpKc&S&r>!G@dc;lgxtauwT+3DAz{M1F3< z5xJ#cU?;;7`bKV2&XfM+Z_-9vnh`_WW)9Kolq6N9pth!p__el)yAEng!U&=u|LdOJ zn(fVgJ&>jc_T_JQ*W3TU`Lax~&3A1d)`inwIJ?qU-$We!s2GAI=v(|7ME0HIIIY zTeQD_0bL~G350~Za>mEqDH%1lxy>mtt^+%><5eLeZ)-+m{SL8~&AA^+5spJOZZl6_ z9wC!{X=k?;eLh9(nLXyPr%xt`4a=txuQE*kz0lb1+dt7G>pgvcBBG0hcuzg(4<UwrY7ft;h2zcan&Q_-2}6nwkS=nrnU5oJ{}Q+cqM^Qo_=DNy@aU#lX;{e}Cws9OlLk3SaSnx7i;`Fw|%s8JS*F2fT<*3Wg{B4ubC{ zp1FV0_VDyqrsqQ^ak*E2k8MOxexOl#AwWwCX3?4_iVk09 zff)<+Ca5Zd+>8Nx*UXglWW|J*O_1T$q9->u_Y=?{0xAST&aUG>7kS*(8j*^~QhhYro2Hw3d!!1>z|&S#95RmyqKT5%qfq z`UPs5$qGq=ir*D*{=(Kn931zceEHC0f2>YH?Y|BuZDa{ z-OvXIpi=jUBN=rX4U9||*yiieox)}*WdN&m*mykW!sJ(h-Ax~I0R z`MY9vrG7h|f70qzo%lbqM-k4BXLooi*Mwf8Qa-dYIH*4Hu*1he-OX`V5-k~*0U}`4u^P*ceyzI9AsnIJ+Yvwaa zL{`tt1hE!;zgNnxLZw;ff4dn5!;yb(=;67)E6n~Qbr%M1S;+_Z9UfCmk16YPtwLwb z1M=pk&JHOpyoYXKNL2;=KNDstHy|ewxJVHbO%X>&hRFRpwCOq>u-rl<7buWH-XL?2 z^*=;lhK@;KE1E#T zYt52=v$%$138?kj|AFRU4R0_qfJPp)j~nJTgER*+ecpzC4{t-RljkY1G<#o?EPnk2 zQOd3C<_8)VD{v@6j}$;Q*aRgBng@ilw_!FCk>;^GRX!2e>%AMDkitaexiI6zBkZ_W zIG~AoKIIzrb_loa0zeu=p#LqNcjE8lnwr z?nm4EdBc92XQ}(AcEsd&+_sU7{Mi>t_-11zrdxTDl;eVxR7dJDou)TcL&z>U2{A%J z0qGJSdX2@;~FF@;7Cx!@)x3p@R>4E|yPPtnr3y zp^(S{R(7Cb4X>ifC@5s0socG^nHIg@JojMX&CI-Kubdb9FnWFLfa208&U06-JPod6 zg*AYfXvfxA(OB{@5;+ItUf?cqi0X>y)iqc79J|$?4PURvlnoGm z6f(IZ%s%eAcF+6dbf(q6gzkCRwWs<<)%$m#)wsHP9vW59&RjY**7@{(qRNh-CPbn<|D`qk(1QB?t(HR84H;FwFV<)wKhRilfr`*A#;(zXVHGtUoRXXsi93# zCz%ouQKWQ0`vuTp3CUtzN89K&wrTg=xQq--kO`9Dg@I!mNa4h%MEGG~K@KGVY5677 zG7=8FP2zNLA(7VFWAj!ZfB>v7uyU5)toy$fRw%tJW?5ZoVpPhDtspmfjPsRRErqYlN z4DZZ`jarzG=dPw63>f^pZyt(hZr?<@8~R7AY-LKSv!Y&>a5QXqFF^|(Y!mQGwnABU z{V=twqvIZQD1e01Sjr9470_9M4IK-uwV~R?6EsCqi6te^q-5#S)&Ka{*oG1uGTh-;ueseI6dFuJAyL-N+m?Ea1^7iGrmROuA|{{D6wzl#bZA58A#|Q>k^0<PV8 ztVJ=(gS0rhRb29U1G4!3RMWK!q?hRQaDC6{FL*Q(z55X$^V_Pns-H0SCH4vmV6UK( zqe5urvTVNprEhq@R<`E`^B(?-L+?<^)>J<^UG7~(n+lMH56^xrYcTHlm9A0!rAjGk zg|{@l{e$<$Mj1=q4ZbXMBb^R! zlJ>mO%J#jU2Q#%Xh@!7jYCFb^Vra+9si&P&Ek^QMaOA1qA7Z#{qutF`s*3r-&A{JH ziZ5f8^?QM6dNO3OfioyiosvHBXDHreX#DT*=pqqn^@26u|3kk&Z??LTS*8;G@yPym@Jm>d;WmTMw<^;PQVe*+37Ql&}bP#_;&DGD`k<8UCX5X zQFZT{qY(Ie!mtRdr~E{FqKc6Yryt4M9=M0qz5X=+$z}5t`S^AC?05nblJ1;(AN3QF z9bqIlx2&F?MP&m_=KhOIfD}AIijszsYFnjp+&2RtqC5< zS5oKvNA14Dk&^S*2XJ@cJj%y3Rh;7|J$I)=I5+Ql@;y40qlq%hUi{Pj4TW63(nok7 zJaaiyEhwKP@|X7_>``-wDM8KxUPGPY#>o!{?_N}epVe%%S)!Y!jHqEC(NDL9&N`O# z56}FyV_X>%dDQ#Awqcl30X460{sX$%(xrhb`&9Jj`6sbJ}^@+Y2R664#F*Gg*2Ln}8SVH&qDeVeiGP!!4j?EDRC z>UhS!nV3K}K9wChUTl8`CZ>>s2{zh^%(;lP@krf0z0KJ$rycSK%DjiV#doJejO)%* z%P=;(-q2jV`jn8+gUO+8ml_C7fIqlC?j-jrw}m;U=Y~2?g5~WQU5t~cvsQQ?_vdLp z1X$TY+fd6A8x7cF!TeO3iNQC)kwr^)y z)>7J`Z{?6nt8HLPPf2-1jA4H-tJj16ex=0!|TdF@zra1ACq6x zQhEiW{c$jsy}6L@?mj}{g^$p033trkLVT?v`2@>*_fn&-A3qMVIPzFXEG6(30Xm;X z_+;yl=ux?m;Hu`_GD$(-eC@UdX;0smQ9H0@^~K$Hj1dsz6*ctlB&R_j#*Y4=SM%qr z)>2!>lOGONEG#b0U?#j~K8&zaV?FI-xV6>QFl4itU$E!L@HG>jZ*ef0nFR!W)d%!} zpD(4-!jI#aoF(-Y;x?xYrC4mTCrpA~7RO6nwNnL!>P&kO_4M@fGVqf97r|>A<7@xm zZv7$GT@UjU#dQ8yx;rR3KOvHnz4=S7rF4V#xsF4JY?+v+g1nNb3-M{jgwxXHyWKNO z@%WoMwvraP3UVn#k9EFWkv#o#TfHq0Q%VM)L};i%>=n<-&Xmocc-(`=hn##i)>Xed zC+}e1J5-$l-8MA7&`0jtb;vx#LM?&E1+exJQq75v)jZjRS8$t386U;T?f2od5Mizt?S!nAM;{K+3WAxA(4E4DPN{Ro(&Nk`h_-Xx1}f4N81YqB948R@Csup z4{z>A&l==+p?0yw4j#7H0jw-m!UNc0+C9=xTf|RrI^sV9eR*Q5ncwb9(-`LETBh(g z6XEpMFs5mbeOy|juoQFp_UE0y9#dh)6YRj?*>vUZ@N^V|?et!$$9kkXCPhIqRn<~~^P8z%?S@mdn3 z>~2OFx4?J@{d?-nOROpd ze&4`vifCI2^F?vzd0a7c@1n9kW;Yr+H|5tWmGk*~hspGTKeNgc`rCL$hW(#fD@*66 zieY|~A)Ej@i={cmSj8lQsiWtJ*PlVWC@Z(l+*q~2r*JzPCXg*yLJ<+P4+s-gUV-l+ zr0yO+DTP!rLvA0Hec%3qQ(71~5eABRr zz$pzm2ZKLY39(2?P!j^}6{q&yj@QniH6t^305{o)M!3b*hw)E5E_(cx^Yn`)&7jQJH}8^5 zVph%SY9LH7R?g{QCw8trpt$_EqM=d6~Kn@*afU&cC6N;r1k^PWA` z#%8F4I~#CPC%%#Z`h#Bp*0dUy7nEf*0BLZ&t9d@oL6MJC@K6}dq-&O?G&$1YeD_Br zZP4Ofhe$4tAI-?K(>v|vZ;R!?N=9OQfD5|BP0;*ZfbqbE^Oo3)omYwY{VyOXD>D-p z?4F28#iP^ctcSEl@jFQmXk+opd`VJYka%phu zJv!R&RqG{EObea2;ktYL8gsuO{Udbi%IyX4-?CG&%j5hm#qF&pI$0VdEmykBo8Q~| zPh&2qn6CZJv9agIxX(5op`()6_OejaT~+X_kUnzTKD421oqot{)3O_1)OFBrQvo@m zQ2Rn|U2wNWGxP|c`oIP?R_H^$daX)Q5v7R-n(aR-(QuT ziX}f2xAL^XLt7Z@C`D{m<1$8L4dRY3P!ny_&6vTlh0L!p(DYl;Uw9qPSrI z89iGuaE_MoZ^+c**ba=^qWr$iy%ISYuml#-BI;$oU@A8M&yYI$bEi zp5{K3zL3Ix#fC%SuZ_6G_ff;8piFbeV=KmAZ|lqt zH~Ic)9I;td_pt&Z*2Zg_x`r2A`HpXvqMMqajH`dD@Zp`kD~XDYfaNrmp(Mw7D~Jx z8=5x9SASp9DgCCm=2@`Ng7L5VZb1dbgU=nq0IPOJX`Rf}8qZ+v{ zCKqYe9%hW!20^|9q&Pn7?1}2s?sRId*#@qSZV^?kC>vU-jA1UyP+cj1`UpwS=|($s zvh(NPO5=e|OS%!NhjX9A2#1}H>t@h@L+s#Z@A%K`LjDDMH_bR=vyt9(-j!f>e)XM7 zf!L|_ZS2$HIHsGaKK6|E6Ymnz(gF=LntU*>7j4{W%|vcC^JTbQ_($*bhmi?5@6Sp7 zof4Y7I#`@YDV>9Gpn^D0O1TVQUEXE)!V}M?JJE}3U;Bi41Cs=Ze{wd-S>Y71bG4XF z9Xk##rkLw_ue+o*kB>8gwSs<607_v(Q|W>7>-zrxO(PKnibv+O_;uGv4wh`W=Y>1q zf?xW6_mzXMW|cLAW##2}XYcy4!$eTCT=b9V8=q?tKvK-w*-F|Cn5pMIKUlB3Yl3P3 zGS&cC6A!*fs?HQ{I``q;lzB*rCm$Qap~jRdMs~iIq_1;<*1db~N3;C==c+xg*O}~s z>$lRKAor9{Vh&!8o(x+Ra*9|2d1~Vu7Gm>`G6%y~JT)xuLSc8G^1uEILsIg^Uct-W zMrkc4sFQKI@%=>Nc06j_M8IETeHguqSol+8%YpacI$yp0-dgL&Zn7x6@a@aLzh<)& zgUknh{ii`mNJ)_cO#^<;5Mud~NKrcBqsDJkfNQ7Jdw=ljHkareQyL92<;z^R5mTi( zkCmq>)z=wL1j!cZ!B#GX>9Zap2+MX`S64sbfdCXg%)TGqML*M58F1!Ude^>tkC>+c zEF~}}1Y?Li)|0*zKPQyDZus4Hjz&85+FB9umD{1k6R|WEtX5oaKArtWHHV&xE+Ym_ zoQKKc7BymMro=k00^bOjApcoQI-Z7m`pg{60F%^3C)<24T_vxX-_@gz*`uP3Kv*<# zO-{n_c|G|;@TfQmAGOk!Gr9w1a9BURd9>NIWL-Pj+_Zk@UXCE48IBn5{qs^+)Oj?WnQ?k-}>I#BK4fOZv8Z&E)_ z$-)4E>Kl&tdR!Ba-xQS!M(<%R2DWgJi^KlgKQsgmXM9N+Au76-&UHb}$Cl&hbjh(q@2D^HHqv!6On$mtlm_y4dR`Y9T0X_VGFn0Zm< zfl1SpoXf2suMN(o@#H|bxIg|~+)&|j>S*dGL@i&p7$f!vovYVA5JP`W1k5o|j)RB- z(gWfO2o){bbRV7f#{48E?XluJh)4Jy1(`ktoj&4)W_|J$%{aAE`kEf!QYGh+gPYEWxKR_C!OVDlVK z?C7_>D+u$a2!S4y9;wpWjW{5EJxfF{BtJ(Kok{$J4Z&oPQ zJM20-;Wh%-=ex(gUEE774-=c2WE99|>(v%6!+J|HpTq#Gf?Tr92W^(C1q7HyHgTJ( zl~#j5S-_uR-DV(W;LqfKj2oQAMOgi2XvtD+rB%{bD&m|d*~=@Em*J%Y#}I67ZIDFV zq~rTzL6FzBZ>IEBtfV{HD0)_p0zX%quumQ>7O`C!JCose{ABQoPMrDXXs<6dl*dE5 z#$dQ;23nqx#|$1Y8gHD|K(0A0(2ZY#>vj7^Vy8O;)j&Ab(AQUT0}hh3be|y4 zs>L8%kn$0p&Lsgj7@|&{@gv^IKi9qvK8LMh9vmVDimP~+=KSP9{Yevqkr2SA(^ff&f zUKaL0JS50Lg=w!T@+O;57_Gn9`GRkRkU2+SeDVfoQF|#fnsMtWLrBwOJXiIjdlbcZaPK;XO0(xCiRDxFgXmRt`S2qfN|Ah-8~A@%`I zZZKb;^xjrQG+amy-iP#Sr-&|PyQ zV>h4tK*sxJ=KuIIs`kXG+f`0!xIo19A1kS;pg9uy2skMZx%WylFQI#8%0^x|87&O+ zs@&JYtQ8HLxbOa09Q#@lbh(hEdiiB{wYk~$*}za1f)&;& z;(zOumB5qId_1AL`9qbznO}{*id;k6wBzr&c@Sp`h zMSI7^J74VcuRi@vMMk~vCqf~Io4aUE50(pHzCEjA0Iw`j1nLpCmEC12aqdITCJ-od zR89&l!1RY*YY@}epjLl(w~)Z|ev4Q#GnRIqK4g_L#m{J2wUrHESTM(w_*{^T@5=Adhi9~D(ivmr9`(Ft|@Kr@*D0Brh zgx(7TZ7lHuAPTlI^k`7pF}}1D$vY!?b~RAt#v0%4VSzv|iI(*CZxuB$@O~U28QSe~ zgRbgn5pVXSgcCQQY)Pk|h7b&FJFBbA3-&$*i*1ea_`!+2HYTmE=5^GT{xP3#q+A#m zFVT8YHa?|tI%NnovAs3NbN7vmwY-{vfrnXS0n!1Q;rJud)PnadW<}0wnYY*oh-KSi z#!(gDbQCT2Ru$QLPZlTt^dEE2Q$4EQsJOoK;v7OWCOUJ#bD-9ma%9h@rSEKabGK-6 z10E0Tl5JF+s}RkUeY`(-ovDl<{oH;DqmOC{C5AFsCWIW$pi6^!?*^Ku3iQfAKjnSA zR>iC53rPdN%B?Shs{AS^XL#7mjKDW#IFJF$Wgm&xwh~>pWjF!bI2o2IiK(w=zUqB zG$0>q=MT=>b?b>Sl>0Iuh8CiDP_WT|h^%U8n&?F?bah-qT)%N+W{u(giVn}$FUF+J z#nwU5^C)6viI`3rzoU%Z&DHElw>dnc+U_LulSS{dJdW#_Q}`1fREhnYIL3v~_0f4D zCVvUM?;kma0%XPAy!3?vc`g|}WrbNdOZbF*$PvxoA?~zu1jM1Cp;x)NyXN)`gwl*! z0*i~UA@4566dQ1}MKOwYzctG}JhJ53T?rY;RhE%|JoV{k0EAuv4pqg(gax``?j51= z0v-=ed!59IhzsiO)v^L>4J3r17ZY(?{kwy9A9?IPGdI^fV(hn8YTF2P;{hb#;?UlG z#t49@>`w8sJfpf7*j+&-RV)#}gl_BO9U$xK=+9EH9xcrdl4OzPu%trtCJQ%ryt}#7 zpG9zX)@txjtKwi^ZPJK-wkYiC`iI#&@7!`rc}H6g$FB-XM18FvwWt1YypgVu#YoQB zzBPVg$v(TjNF8H+zixgdC)056`o+r6B zbkTqKcXQRlTPX`ebZ6&>-ksb$-0-`O8M3R`|G_!_W27^HfI=%qf8l_{{B4JdlsGde ztf?tSug>`EVr0&rGl|d2aC0E4Jd+)U3XMxM8$F^MExo)(`{Ub#;mS=ERPNKQFS#PJGnK zhuOqm*C;v`UcK=6loX%VcfQI@0~+vyj<}L7d?;$gOr|*p+)&g@{y{3WGLo(o68eif z`1SJJp6SUHF;UEw-i3^KzpSgstghdq1#D5wq79p71P8rpHkr$Jvn@yB#=XrVL}D?V znW|+k#Awrc(+qeWS6@=xv8S|&wDjQ~Nl@EfPH8+i^w2>Ws%}j!U@!mkW2C;8vR*5% zaTPC)+ezoQcB`+mBY{5K)kTE?1Z-|>T*j?2yGyI$CfR+n24AwMg>5(rUaXC3~0`3j=9bjd}m6RM=Z~S5sAMiEJp~2#|?p7)>I9*Tb zBmz+*8_m6v{%$;3U-SH~9i5s@N#zeIIXm;?;NXq59bQF9&pb|_!O zP7HK6g>23KdLOUc`a3+-Bv@zg?()!FClcjq?eU|lYaW&lHc`=}dx7}<5V_!=znAfp znJ-pJPF^10cBE+GY@3>Dq{Rmefk)J6E0et7WBDT%P+@*YAku^|4$ zK!Z|KQ?tFRi+dugWr}&7>Gyg6ac>gk;gwOh_WN#cDL8i*Ow_X|(M?x01jD~=CDrN| zvIz>l@9R^CASg*m<~k!l;d=ooB{Y3mWQ*s-Ry1#6~8&T+s%&G z#VR)>!h1SHs8zG7i*&CQZO}CZ_;`IXMoFk9-FYrmEJvikgqykB5ZNJlgl(+R%Re3o z4OM3jsWRs0x|cun6B4j;Lr|jY)q&~hS0ykfF7Y9`*A$}OKRd&259g?u8zLO~a(9+sZ3{-*TcC=#9`HnyCucfKhzHisKUNfBj+4}5Wy?^=8j zm6HoN{Q>Vsq_x=Xdoo#{xHeAza2z_!d>*LXhdu?qA2R-(XTa_Xvc%Wtl7#QQa_h&n z4%1}f&B7(dTgLa(X&%0k7r^5)SS^_JeWgmkO-n4(_adaa9C`MG$S9F2Onz=O_!q@l z4TUlDl`IE4CE3t<)bg7X-KzUI>OyjbNjO$VQ>5V2?19oAhW@S_lc(V{Z4EC(*eGn< z=S`k``E}spg3quw@4`}ZaN(k)y+rZUK!Ow|oF`Z#PwV{o^A}(fR8b*?@)5!c6$W=2+4_QIu0vwbA%@kDL+4J%13yDZBRA{ixKgf}awZ7!(kXR^xB_BAVczsdV~ z{M~~!IuYk@J8n8b$P)SmB}u4 zx^5A3=Qzx%TYKHi{8xee118Cq+PRQ}b%NXdWFPv= zY`O1JgtJsSiO26W4m`KMazB2!wM_2et{(T)`{qUgeU)W)LH#zL>8)Gq({U?>e|MK{ z>Ru%)YEUxy2!s_H+%?|0EqX+f`^asEvh(bO0prg%R$oqnH{B~;&}hYwy|P(Ket!N(UwH## zSN3L%k+2`F2-r!Py>KTkyyd_dKFf0II!)TJ>}>@MV-1gk!a_y~=g(cg6JH0fih3mb z5JYcp?(5SJM}Jg{KWcfbd)6@sc>ekMrzfYUDfP^6N9`=WzovtKeXHYUTD4tAi)ES* z7Dm!kV$z&&%M2eX;7EqMvnwkG-vV4bm3(;(D(y_bN&x?dGgzn)_YsuRhM6J)|7tZz zm``^8=^!V>iP^PdUhVT0mcVd`oqX4KTmSW^&sXPt<}YEtJt0(@c+ZCNRrYd;$09BK zvq!W?uB7q%l<68Dk?yZKjdYCEpU(DnFOHT^$!2IW7w*T#zmHeYp!`5^W$`Srkk^YW zwu^6fx6YfRCLb1*)8ayt{h~GV$)c;sKzjp$UzN`V9G1MTCs|*eiJQ^-_zXB(CMaQV z77Z+nT8TF?PWglSlm@%|+#GKcQ#zxrh+0j2yM6KEMRMDbenEQGCHa1ATkc(8!8P8%}_yRW~D@bZ0*cj#&NJGQOzu|l8c;e`S2@WxYmxHae8 z-3wKi_;LC&ybw&n-l2Uj?y$155|S2-<&6wMV!J0glIJ6%#6M^IEQj#=buV(CusW!1c zP1?@yd|hO2+K$%^P|U-MTQ$6hYGUPbN0lUB<|xuT)VL^|xTsgNE@nGY*w%(jsI=GT z-x-S|W$x>nc)U&MD?u-E=SPN~I#Y_skmbOn*6@uap)`ij@42SM+Hktzojva!ok!u= zVapC|pTNe3^@$qfVXD_wT2r#_nZ?xP}J`aakqD_U-?(x3Qa`5acI)6k*{$z^Iv+aO1$LSK2RJ@DmA^*k+F{>X96(F^C&vhj%_{yZ%ki`N^iJb_8oHC*On z&X1a-Z6{Fik!OPzniQu?Zz?A}pOI>0i2NKF;9zHm6VhuaK%`}4QtIs*P0L&`whY40 zkCJ76!>Kb@JA(b$-+|D8iRND@cZ$ZwM%a*=mS!B_j0kI)KQMgS?E|dOP7Z62*K6$H zOtWJ7?zqJ_E|C-@v z*TiEdQP5JuVFTV>c({$?SfWyYSRTfSMP(m8f$;45rnA3pHIYn_YPalV5B=WV@KXDB z1EaS#e%fTrC|ur_u{KN+p6>Je(W@PY#s;Q~F&NmUbg}P_o+l3athctL#+q(^^7h7) zTMNPkbzaZvUUg(03l)gF3nZ#QrLglt9KtPWL5+O$o9?w7-uk+J;vhW_Mfcy{$hxfY ziCAY(B^(cDSPUb5MN{1UMo}wMSx2tPx&3`U?d;ZDz zLc09;3$C-h1sv2+ev+KA;cjbVu}LiaE-Ks;3EioeZHQy<3yK)8-XS?>ki-8>ePO#i ze|ze2FVEt^mviLy`)TDy^@7&puUC$%ECzQ~iHKZ#tm9%ZK{wyrXlSz5;vBCe|JhFv z@N2DN#q`hG+P{ru@YBVlcVxA@qw)pR?`mqa*;0Cv7B^~Mt*=RUqP`HI6W&rOq~dz_ zvs~3LjQjM79Rk9k!piQ9#CA&_B=VMkEd07!tO@B zy{MH#&rNc8{Fi>-`A}`kF!1fGnS~!{mvdB;IPmw} z{<8`D2#~3fM1DXVbZ~HR{Wd$mwZHbe?Za(bL}*0BJM_(<>d)c4IJ_$#jUih|ztC;@ zcFxmLCrJDjf3d?}H#tO2vxrjdcroc=i<86JMwTENSmkilK}@{p`@E!ODRfu}w921N ze3SMg$+$PEaz)4RuYiHwN!^;DNMZQBy3cnK)<2(E3XUcm?l31ycvk*s}RP zkWo#z{Vrzcf;Ngnyr$)XpA5;EAoi4B?DiHn{Zr}IS^E&@rz1~?A(!mD^&ykeM~q{s zxsT#pqoOfobTxI(*A9#R%&qh$MN<@L+{E?zF>V9bw_w0fxBy~3;e90}BFfOt*P*1O zd;%Lgz&F|6<+(l;x_3sn9f& zb};wi$Zn{VOKh5)9waeWO}^mb(J!BdjFs&KwEHb%V`Gr*GGRX;6%UxDXwk`!1szaO zn%`Ms2(vHj*54h$lL5gY%5&c%!y+QM>I%*bV z4KH85RI>c86BqxWyTo^feC1u)ma)m(SUNSHKdXsmLp8-C(t}iX^LUWG z%!!K|=z&SJ4I|%na@XZ-d+1w0E{<1iDqssO_RanMT-&%$yUl3S zpPJkXpLpE7Lv@+HKeX4FLDluqn%>LD+SC!jpjp01N2ge3(LFwqlJ6{g*2z=CH`gKe zF-3HyDb@I~QBJ2p*B&<5-YXNaM%C146orO5O1#*k$33x~yu{d>htXaiY%R5V9*e1gVPhurB(P_s znu!OHhlL*)@cum|v`LiW!{2*PpKJed`_^%G1v~+w1shRM%RUHuE_2^hOSysi#8vja zl6!kkKI<)%e?PxHx1EGuDgDK>e?7kI*RPjY^|Ma;VSI)Q^kjfVh49*6H;3nQXJv$< zP{%a*!mKj@2s^2C9OJhQ2i)ev z2dqmd=QzWyLsn+KDac=$B4jp@GGEh@*qQv4z0*B`12#?-V`@oev5SKb&I zDcRW3wLPv^UoWZkY_p=;#j_9!l|9!aSKc>|MKF&iwyiVGmh6p#dOFqHfxv5@+1*|D z$56TAxk;~5LgdXAH~L#fQVrXTRt}$}9fnj|ROu5dFv_rvYITNb$tJ zXH}P>_SdIr8Q9ohMIzf+qUThyo-O|QZnrQ$kr(=!2G@LL?;$bb-ds zKR3e44r@~o^l9x}mASvxo;=9%e99u@HIik&{n`FvOk!dOtP@rvMHA)>lOt>}s`+KW z@T=4uwiwMK9ea_@4w66{yEB)M*fY-Bm|O%k52yFb%3LlkjQB}$?9-gI=k7F}8KzqY z7smxMPG-~QC1=8H+PE}4uDkajcD9^XFI_Cl-s8rpH+Lj?@!U4pPrS{}W`*?1SmpG) z#iNnG=tYieTv3d3{n{q@(?g%MU^&1I4GYUqOOtS28IJVMiffx1)wve#cb8&CCu4RB zFb>vJ^*)8feh40e%6T9qUcY%W1bcnRuZTE8)@2;G9_x%6p;MwCFU}qMNRTH-Lc>SI z^{=Diro;B6%2{2*;^$ULM67<~k6ekHE@lU-#q58))f-S}E~(vKWt=DV?q?^SKy|nu z&->Ws`DSs;frJTDXB>~M>Lx`|DrViw z+%uB>Y(m88X>hn7_BD<9`XTej4}-a4Z7zQ=3j`-;TTgB2V9bpMC>xBfNG}a#2>oRe zeb)vZuU{1#jERYQ9@3-BA0+HOm!qQA*X4J=Vifec0`R1e1k?yj#~ZW7AtZ&S)}!h2 zHplk{@~)PDx^J0J=6w1T3eEF@yoWad7a6Hfb;g@BWRoc2BLXXz<;G-PcGAiJ#noGe zWw~wP!k|k~Kv794MU5veRPU%Jk3=mL|?gr`ZmhKX1$(L?vUe0*d+UGmh z_5IjC*8YJopE<`IJOv)1NQ5wRygTb}@Wcpa%H<14HG??ni_JPxdrKgEsUB{eF?_TpQBvi(UiZ#qYZKlSbnyiW{a}4edCesKQmV;> z%R#N>MDHH@Q(gfe`2ShkafXVM5je} zu9(0Z(??@J`ihy+LHaa^Qz#F6NV1fEj~lQq*=WwskT0{F?|q*A3+{#0-#gxZ?$^9U zJ_Tfrm|JpBs4AS4j#+v{+s2Eo^bDx%)k>^U%9cHeeCYma_TbW`QnP*2Gy{$L7aldk zh(0i&MFiGnb^S}&@7BLA>j%BI?k0Ge62v)z9UrXPcpV>KsqR@H@6A+^B@>7p0|nH< zo9tI+O8gs!9$nquBVloIJ$0U^%fAb0o;`ae?@pm$duAzgD0IqnT)DEjDLtmbXe@iD zWrHW8c2{&a0r;S&zz3O4YGSCEQF!1KlsXY(uoB-|ZH_DdX@`1LNO&igS<^YFbV7;G zQ6ji!b&@SpDJzP*jAY)%d~Ucciv>`GjhIjho};~&N|RK0O=m^v!$n^Ca%;vbpxUtI|z(Z!pjIYO_+toTJ`ef_g&CWgo6W`xCk zkJv1<$&CXoM3V+OLrP6FN_R*lgQ!{z>^5^eO0~Myqf(;SN-CA_W>gW1>u(;CRJ{74 zf9xgTFQpLLf601zQ>L8z*$pN);9kD7$mFZ%$BT~dtH5u~jygUjTr#PG5l|^>xVwTY zekG-o6)lA(;CcsO_E3c*R$^x%zIE>9D-8k1C#H9JQm@T_;A}K5E_REFujfv)d$4$k zHpS4yENeuo^@dp!SDXXHBn%Q@JP8EkW~@&>BwU@M9Vip-Gd?@apfl@tKRGzBmfFdo z+$Q@4@C2xK8=HLkT=~C-bSc~9HyUumud?`p-PHjiN1g2jdpE z(Y`m|&&_qfQ+6Oh(zfs6iiq8hiL+Qp+uAK~4Xe$4Ph(mllxWqlBjU0{$3(VvMT>`% zy-4q7U<##uvaK9Eu5NTD*K@~P+1|43SUspt|x(Zz40E?u&EVqt` z{qmBW@_EPXI}(&3bGH-ReyK`Xm4@T=)&T*J_MAd4#N?pYQ#4u(bmDtcU0}!OhV{xy z=aTjHHGh8mu#bFm~6diD$-bkPmW-ZsUvT&Rhbhq&~Sj~oq5#jwiJcx7v z8sPJ%PYrDucJ3H_0Ueg}9l;7AhK%#yp9SKh?EXYJZttz){&VHzowMku<1VA%apGa| z2N5zJJm(JPp&!cZMzRX&cs6QFxe#c3N7zdcq;iX4>bl=xgJza8a!h0`z?}E?ErtXC zlsMfv@wU@@%D~_?lZ$LFEkZe(8)?mr;!bR71I)=^lWJE7Skleua7N)K@o)58750Ik4^JYvgz4gTk{XKZp6P)AljZR9MOKRi7Gf4FU{#g*=O+Q z)JFFj6c)H2TKijKuJisVu%Cha)W=!fRqA*3gr{BhwY0d;_4)zxg=!41%VGIohDocE zVXcj1qryEO;`rwXq6f_UEyG^=C+*z;T}ro9?T?CKQSW5o(lKhQTm_eI>W#C|9%Ga9 zUI#Tx*+tvVEB-i79^m~@ndDC=3H`wJXwMk>G}%bDcV6cwJK*DNN7IRX(#p>{Q-`?S zB72lPOs1dw{pVml*|#!_~O%T|7B-yuqE{s#;Y)W&F%SF2zxlfTlCj$PHTc z-UML<5c2Ho{?KSFC@UBv{I%J?hdLoVpyFL+$9|VNOtx9)$r<`FqIM%-L0FMM3LuYw zG0VDDycE`OvoZU@Cs!J98P@omEyF~|m9n`6`P@mH^H@*Y537*B!(x<$jLTeXzV!lE z{LUCHajv}4P+oCt^(*?lo8R8Py*KS{eD80wXO~9~Fx~)?z(N;~$pT^yaQ#15u2jDE zeZc418=I<&aeNho%_~+n z%(_&e#NR2BW!4Ra?g7Q?JPi?Qj%c4BD%}(_F)y(q^v=jZvjFyrg|rCW5TsbZlY!na z9Qk154?<%FsL{K*J3cYoRtBSEv=m*|e$pG%rwh7%Bj0;+k|g*`@f@7h1x3X75(Zw+ z2mj4FtDPnN7);S(+0AsW>m$MLu`}L|!y52tcJ(ac2dlwmA2+Aaw;MLqz9W%RiA#co z-^OI`j9}hnWk8=RyOn+R^G>*LHo-0*FWYGR2JJP#So+~~lcKqTx~H=y4t8uPvSYhO zF8zT??D_A7wjJg}!ruLivJf{@&C>Dh!$VX+WvJ=kQwcB3qT*siQ2?ofbPrPJgb8AL zddDfT(BqN*1FwxXMWL7bp$n;5mT-LnmH}k$gM0VhB7E%q`xHeUbIU6p=)W^~FCw0Z z=nyL~V8jb;W3QN$saI2m;ru#ZI=S?xMb?;{iCgE@-|*tp*qT4F&7vyi=|P)Ksk7`x zSXJ;mbZa1a+uu>WK3vwC7aQ9d^#1=mrxpuTR6`5cFLgh}z5}t*9j|9w@|8M9UC`z@ z)jO9IWQPani&pO>a%Z`rl{Knq0*x$`*`mA8PIumM-M^?Ue-ZGj&GER$oaNrr>fF|3n-L*)9(Ps)5+op@sp^ySfPT7&com@R~KW-({B>~8S7HkZh6IKd$g_3@4PAd z^sR|ikQL|)IyxA180R)NbgFD*Rpk{YJb7ady}LxycJkEf1=BGqysxcf3H+D}l1?+2 zvI*u-lneqb@5F&gq2LPMDZbu4R@RJhs~;-nt@t*gZRy5O3)dTU!3-$6{Jr=#ZZPB%jI?V*9m^*Qg0=cjEz>0~bWR821*{Z@c zUgjBfR>FMbbi_swAvXvwI z4EGz+y}U8qS)RDr4l~@3$oD$3=lji`xV!piLn2-{qa=>SkHpflyk^Ihao%Peu+q{vnv_l`W~=6$kJtl?(bdyq zG;;DJH5I$?(3T%dR3hy#P!Srs=)s7iHGc)`GOgT*?#H|yM{H0a@yNOVh1y4GiA7lPLdwV@@)e=2yVALcv2Q#M`&+ z#%Kq-xR;~qfB8#qL?)L434ZwK{`~r;dHHNie{kDS6x;`iOzfgZZQ4B|J3 z?sxcHI&odz`W%P&{!W49H6C<{l=a z4DPwp)&5R>x=0!>lR)G$X)!4L3Ih@}O=crMhz14*p1yI>s8(;WA^%bSrRYb|(2X}9 zhpb^0AN?5&PwWrB*U7Ib%K?uL5I-^>%g6Ea8HF0D7i%!5W@H#bq3i9Xeel2+3SCok zvu43~Ly;A)gR&h`;U=rUcH4K1SWBiT78|2!ZY+PB|Gq8*fe&<-F6RqAwk{siES_rU zl*^)!uY6m$JP31@StLg;YctmO^G1*~1Oq zC~9c5@65Nk9*mhBpC8U3s;n9Bi`p+3xYUC3n#X!>7X86UC>*Yi354H~F*jc|qN`=_2MT&#yDE^CnB=QIoI|8(B^QT7l6cR4N$E*Sy1~B22xdZ^-|g4AILOyq@`V4m z!(oi~=FJVTvxUI-geF-Luone!<&DSG5E)pJ4 z;80IO6Qd3W!@#?bJ2=IY|NcNt2Zc8pGb}9W-kJQ(0nFIHEA>eB@tel!wt0orGR?p* zt9d52Tei;5Ei@{87nEJIha+uc@g85g_i+W;QN$m@IgXf)6^11?#}eg+$)J+#FAvOz zgieDR%RjmQo_4bg$9sQ;cT=A4uAf>i@A$0TFhv`^PM20Idc}rWYE+vJ#f9GE|^xxD7Yf|{Xgh!c`yz4@2cvi+n^Bb zrvvt9PqCSa$@z80M*Ty!N$%e5BTx{0GiH%iHH%Mw-5FBwa&&8>_fUO9KxM%zJRfB0 z^ycRJGnBGmUOYN-IbbHI7TZu#L+>4q>~zKrTnJxA;Ypo#lj0zXm+JB%lEUbsD6Zk> z8R1H2K2;GHUfM>p?*}i1jTa|mK=k5Iv?kv2{TAU&V|2jvWKT==L?+_^N>-h*E7l#} z$z>tHoPs6oZhnkNg* zPo<95#!H#d=#hz>>Y6z{i2gEc{W1%$*(?>dQQ4nhClk=g7Z|kQU;smfW!o|^6XM0J zRq_eSlKt+2lmkB{z|J%*EWKHtgd$fnUC`vi0$-lh2Fy6~YzcJzpp@uEVI}Rn(R61Pxt`63c?P0nMcCFzO%S;1}nVbA&4juy~iHUDPYfC^tpj;KKU}XftfrH}E)I~mb z+8-tlx;o=OxO2s`k>7*f8|2M=56;5q0Q3YAZPZKaNKLL`Afsv~gFk-$~e{s$V{~`+JVttV06bXu5omC0z@%9w> z&|hx2Q-4TN+u)yjCAKs3W2eBN(I_Ld6ZuoO#GVNEP47Lb?{C7LS$I|EKEPb_mb&(A zg>>!cz0p*sHx8>;s6^iF`OUoVUFMy$)3XxeE&o)*$ngx&D&bjPB@Dt5rKoM^hm;0q z%Quy4JQj||n8R%t7M8EvwOoCnGV$k)%SVmZ*!()?2K;75WWPYeb3hZ&{-Gm2iDmza^&4sWZVLCl$ zQZ@NcdIOxxBOSXX=CQG{NsqmrFXTKyl2oogA5yQvJbreJO29z=FX+Dp8`MQ|)eMWr zT;S0jjWWwSu!*~4`9k43hI`|v&l}yGUytqt>E^S1-P)_y9WSW9i+mc-syfbB?t02! z%FJR)DI;ex)~XFOeDZQ~Y#Cil{l?Y4sXL$Z%S}ii%jrwaiO-!<1%ly*6^|oxqTk`^ z%ED|PEvk?D>+K5`>ZRGDtOO4ov1sLRot@LP)eLFz0}F3WWU?5IWFsV|0&h4WhInbs z1^N_fln-2q>h8sVh_8D_K1p|xm_FXu4!36c^XCpFt*WVC_`dGC`D~$HaJVe_i2ue! z8KU)j{rUmaB}lPUW8dD+5}ZDwCK!$gwqr2YlQ(MM@zy$aGh_TK%B($9N#%3mo0Pp^ zW(9pRiixXNPstvn-t^Y(@h+JWwAZVJRH~-~q#$P_)Q8(I`cTRWk3Cds>H}!&up1y{SCb4a zZ9HpQs+F#g(5oPP{?ng`$pw9kVycxYyD9R$E$TS`nJ=qzAWPjZlSSg~t^||c39CMH zQ~w11svg_`IsOT!aP#-19_iD~tYaWrnCtY&KmE!$dncXie3MW5X4hfk-D;f745<`% zX1uMtw8vXG@lm=7K6Hae_A*p$f6;%4RCB{5dSCJA{_%TR`}u0t*;);E$l0MV&?q#Z z5R${c<(YP&+1c6AcHbyNSwT00F6lEng>DR+#_5i+WJ6M7nJQ|FPk_O33`{89Ks1E!ovUk#sU z-;)+?wo}DP{9x>bs$J{6FoP4*-x~wKijwe`b?0S#!9Rmd+we&$&krW}V4M*?+rA9sbd}|vNyOKnyN&PSxoAdo9$Wy5-b(}QzAdyRXFF|oAJEbk!3}hBxTWCXAqc2R zo=RfT#0F&VVZ`)Ez*9XekYE~yi)9=BLi*ioCxO3bHJS(K=f5qTrccm>vyEDFSYkJc zHe=tuL5^6wpcHb%(9~%U&ZgYfawokn&RMQ`KWxke1rZ#G?`>4>Ux0ir@V-FH#M^Xi zfTFbv#&AB+et_5SF7)_lA|6-WqSx0rjJp%x%(tEaLVGO&E~4OJQ0tD@ zL(iC^(yx~2M)XA%M;AqM4Xaf3y%Miry6`MtxHO?0qvBQ_v-^8PZ8)4$YlP=Vu%ba_|jx3&~uXf&Iy;e#MU zfGEDvNJ1-`rq9M(aT3F-w>~qI@Y?%FzVfsSVA`~4RMqkgz4KQxH^{WO@We?pp3>39 z(rYVUIa!P3O~oYm__oEsaIp+8#0h0DB!e3rE$F|L_yl8wk(rxZ!OI~eCmAD1`|Wk? z;vFTT!5`l~B%O9^4B)G;2(GcfH8nwk!<>x8jLVsC=!Ay?YV+N20+;0CgJ-F z-|uIOcGyJ?ED8QqlcTqDXXRebjB6ossYJfXe{VGY-zG9=(mh0AcSb-s4)xj^cUbSx_s*h0ubXCDaLVrE_S|1h!e!1;(Jv{(-5zE4dhuW$n}{Sr-AbS*{W9@jKohj- z0)Gn~!nd-;x96`9op`aHwrzwv(<7I}^y!CK))yOr2P;72~6MhMqHhX-BBDs^7pL76q^_ugOtDT%N>pic$`va_rx2HlCE`Tu-+-;{h+iu1Oo#iJYCN=FstC*fv&%>!UMA-~k zeVxuTp3Y-Zb^uS9=XHAv+*s6<7OUHlj zqXoY^N22{zGPy-P1%$!AHu@FRIk@n%kc&5lFT;xQ)HtLZZj!eqaeP3@-!?X?b`e zZqY~-xa`agPUuif_Qnacf%S2$#+AdS{+t{C$$q~Pb>V^&2>Jdr`Qak{Gx(W~{JX?_ zZ#Kd8@C>-zJv|fs0iD{!IcYWJ8%aWU_N~-Ck_#f_{jt>T_Em(sxKVZsH9Y1CSR>;+ z{LejOBa9^g8~OBqwY@+CBFa$EZv?w+aYtJU?x_;1>4f6Uw3+wPJU2-+vEbtQd#y!b z_wK!81(zEj8z?UZTM3ASKMbO8kfL4#ndk5~L|DoLN?e_rXZf}1M z;7|Sut#SL~opqE+;h!ivP6j7jYA*@5@;#%UZ?CQ%^I1QrO-Ft%*j3`>B~4%BhCfIP z_2`zZ8$*ROzpU|izjJ`=q$hbX^UZ4JTY_uR_y(}FCCmIt(ub<+YL{vPmMP|Y+TYEJ z`GLFt5H@`*R4WiQCJpf&{tf^3?HQC|#6AWun*_hiV~6n`1-@yh!jIDQfNmgDPM6h( zrmf*3+$C1XGa6tyOazYBDzkKLd36ZuZr}Ih@FqFAjGbN4kU|fE$fwoJ?BlJlt$-KD zoVIUlm|Be)e(L3BxXbv>o{K!Z&{-Hf8;wmPxBu-e5g5sM-zKy} zg?|VcNDB(s5H0)l>$N$5=5elwtHq!5V^^y$n#_k6Xa*k9yNz=dvK4vLe@lwEi2b)4 z$a@Igz%3#4kzw7@94=gyVgOd+5;MP=ZSsQ$uGm4E3p-65@W>}#jK$E(nV3WbEghen zK+7csjq!?^EJN0D4LSjjuoR^iJ0eZZ+Vdq_CM(CJ+>9h&m`Ruy)~k1xPHB zyMCSZ0nH5gmfJUAVXO0tFSgo$*>v>r>uflI0$0o7j^2h7VM|a%)u&&9Du8%P#4KSV z%xg&rC+v;Y{p|=a^#aBj$z?$dT0FZ`>~5foci=IZJ@^EWXN5`1XZHYZI2uk)!naUc z*-ZQIK@Pu0!7EJQQ|fc#K-A4dU! zvH>)@b{(z#5Tdp^%mA&jW`!*^6kH>)4*YCu8v;i_`Iir>AK*>i#l^6A`iucnHbSh> zf&u)n)=KgT{`V1#36;g|;=I*O}ISR}b!OH+~q)(q#PN*oT+|M!Wa+aN>kyMzmhvd+Heu z{Y7Qj%Sgoi*dz`Zw4jLVDIvVw0I~>N5|#(-?BAL{;&Z%izX|&qVHLC=ld0(hjHZSZ zDEet_9D82h?wk*FkC~f)gzYD~gY^fwy!4wt5KTv(9X{em%R60coop}VGqg+P0$|E2 z9PR8Rg1LR)zentKVw4c&*_~gklS%pYA=^AqmN#qm}-{X7h&{#-26!=c?dskT3O*0>nej0yRL924HR5;m7THBqX^~@9ORGE;%AcOfk*2HoB>}2Zn5PCx%#^`3ab&uj z{D@!8^(p3d|584EH{VOh;L}BOZVCRveDWhQ#Pf1>$v*97^ws+!KZGpQ@<%zK>D#Q{ zsv9I2HTMs}Zv)bd4hknod60Bzwl{NPpl3b;60#CR!1RoabMWqyA%F~Gl9K-}k5*Rt zV*T9+oM zlaGG&Y=dAiby`h!r|zAZgQ>Zp*u~9%+cFVRD@Di*d}Eo<}!$ zn+}l>F2(1=e%W&4+;RxG?55%hL(xl}=WDHG9}e-;9Ebc9Vsl5=KEpo(Z%)4g&llH0 zsnz2sm#x}Emz@?8crwz(-JO7ptn+xUrG5gz5D|DVll~CPncCNuNTJXBZm)3LKn`)H zO1yC5cmu0nTZXn5o4Af@+!?&gUR=5Fy9z13GV+-$He((?>ONHpPYfK1Rb-YE!CQ_m zUb6Jx?`-ea{cAcUi{O5WI)M9?`ggoG82O=k1{~5Ed%tuG)*2o8B=2)|^&C4$mY>VZr$e$1Vs$)0QK^=cwDf&y z>UU`}5reS7=jP^M3()b8SEj_$76)bs2}zY@&C#fCCjYj=TghWvq3zS2{&V9$$5sSX zbrn|*ojwK(F9}6mt$+X8!JMI<8_SAZV_yUvE$AP`eAm$c8wS4c85<}*^Bt4g;ju+F zQfWz#hey|_#n_!u^{D#ZhD@_1(2WuTp>z?cLVM#|l;}f>Zx@1c9oI%4%J|jR)JR9* zB=o&^CNb?l@vW+kSuBb!a<%=g`R`YhgRkiL9#}$9C^Ksmyah4vEeZ-*XkLK6K`c?T zB)z2qkB=6&DEuwGsA~5`3t!&xjtkd6H*ej=QU_hZ0*HPbHYcOrzWqUBO8_5n9`j1W zWpbgG$b8t({0aA>9Vv9qZ>WBpYUe2baC@j?ecO4q>B`*vyemA`2XfXbixXPtF6S!* zFE+X#yt(|_VIXrP-u-KIkHPEL>Q6*Z{SdIZS@F0pl)+yF-l+ijh7R`M9Kl~#;uJoC zZH6VAA>gBR+3kt;`tAt;Fp@oxKPo7h9?3|6!I+pu`%^MK6jcP0885S1>kkbbES5d1 zn{LRXG2ZQ|qjJ3Z$$*1{sW(_CPSAU}PZcVHWDrG?Oa#l(X$0lt&d>_QwrEeP7Z|c9 z{}{eY8sBg^#u_SVriZQRZz&NULnX2IVew-P2wnjmD)GM-VEKvUHE_@ zpf;l2G#?{cyI z+gWy>r8ybCX}4Y|{M=Y#HG6DxmS^`rz!BtAly)J1-Usska(jwt>pdtLiSrl~4G}h1 z6W3~T?=@=QOfx{Ac5#@&57p6Y$cVG9XzH*j zko()b)1db`hgHmI?;UH^+2u3TiW61m>{{60em7UNMT2?wLg5>y=#hMl9e`kOE{0x8 zym_IZNC+3cq=CVGut7jpb1Yn-aI6*Tz0Uj1Da*e%zb-5ENO>3Njyr&IOR}47FBsQt z58$9NBUC+z$)bBc9@bIbW%v1N$xwZ$u;_{J{Kn#u=J%|utkm@ML69bZOPO-exJiO? zO)v?g0xc@*7d2wtHo^Lxc4MBRKSjETWT$CkmNQq+X=e+jHt3)BhLsiA9amNU{cvJ( zsMWJW)RJr&MNz0#(9^ZWDxWz^i6;v3FGjzdl?wzUjJn=h50%_1Bm1y_BbObvrqy&z z%b|tO0Q}9&lG*G&ZEa)Vl$m`6TX7BtViADmfwT23GO`__5s*gMslr|S^(Iw<7Z>dycJ9U5J zmP_`h#(tZDafE<`q>ZCbu=zWKvi7h5weQW+K#RSErqzw82OAuQ^mw9cl#P;@`D4=+8+7T?#}GaTE#tK%#$SVR0j4-<+^?KK%ZXnO&rl zC#JYx<^MN2M~X_8Q5vEB_n0T-qugm3oygI;;toLrx4h;4QJf9KEq&PKZD(hMIeMfOq)(@gcZ^0r!2ipeV zkG*tZG+8Dh=(*#A+mW~EhdN~%Z9AAi6XeqyFO3WaB2XW3H3e&M0K-q zX(L7h5IWyXw!Tj9_~k#J1%-6UmVYgxh>SSW_ZI#E;9&LvY=Yzvz^sne^6Q^JfBp)t zOvDHQ_2R>Ia*5}k40%-Kg+hAX*Y~}lZ6+62&hN|^5&zXSU+Ny6GLTvL?|cgZG#&q` zxc-}OcXsVAXh-x|Wgo62mMLY>G5J&4I8s~1n1XpJXHwY!lu!_}KpH3kkv^X!=8udX z*3+&$=l=uMxpYgPdkLER1h-q9)&i55PZ$$Ab=$j~#Rl1mpgMz95~6GU;Eg~%Y) zIoaCI3@s4doXoYN-HtE0MxwKLM$+&G77~K5caP2vd*=4mg(h;8u$RC;#wbHps3?xN zMxwFFP?*>59lzS`CxZSR**t4Mt-+;eM65a0Vl0d5_zdh!xK8HxGdi&m=&3%L!=u+Q zjeLNb9nPvJ53@2H5|f4YZ-C&d@f9>)h#(0TAWoTEsJtKkz{qyHgfeuhyy;3&Wc#J~ zy4o?KQ;>!L;sRPEDB%b*^Pej}ICw4MbIob9)Isb)?m?fN=q>iYL;!>)S;YL2sk14c zKpp|c*cdOhUzV65+53L!&wuV%I6nz)im*n*utqVkMoi8U1NV~Gw2;!}Q^q zxZ?6H!@21lImZ1+aK}ePeALaC1cqe9906n=KORi#(#|{ho$qBILV!gl7*zYIRi8U= zi|YABZzE*D;e&JtGCh=Y6E&%zXQ>Np`3_UK$K_m_NfRIFP`$t;75fLOXn;=v157q3)J|F*!;{eFXz|gSkI)i4Vu@@-1QTjBM zw0bJ$kNl@v6Z4$X@hmhJQD8%VL58*AvqtSB(ZW-1Bq3bX4-#iV@leJ=9D6LNUjPpp~ zERN6q0|2#%dK!TiGX6?Je~`(HER9sugM@wq74f72H^Xwx<%#=Y9X#Ty$9%vpFw`8$ zkyT3Lek^t6Qd4H}`eCm<)DaPL!ixf|7Gl%5AD9$7m4Dl-d03(ZRCzyuA;PvOB#q+QwQES%0Mib14INN?!A3gtFr^x%O`tnIVqGWePnBvh-qgtf z4CbyB*89sPfJx34pk5&YwZs8aW_YKmv2g^)2U=S?VIip?h6a7lT>2Jk>ffW!`^tnM z;$)DT4o7c2!jYewYWMA>KR?O~v~aSgdRrhQaqy&wzKY;&x?^QvAiYz{CT@- z#3BNHA*%wfJM%N2G5Fu-z=V^;8w=KING|$kRGFiqeBPhCx7!=Q@^?}b-N?TQw~sK~ zK9nxWwpOLW4-8_%uQe0iCdL0s@vndeQakxx-$J z$9}}|M@M+#+^D`YCWVgAO>tVwq+A8N@F#!HAjAk&ul?Mkq_W|3a`;JqQ`wL=oAve1 z3Elw}kFx1b_OS7kda@#p%VO_yLKzn5UqQtO(qrW02@2NiJJdmcPXJR5To1hf$7Y{< zuz=@p?I*)qI6gWd7e6F+XD${^06-zz0I=S05Jj^Y{JaY8#3lea z1n0!cb|L=_EV%;!Qkj?#+`cUWlqB#5Ms-QXOOdXtL&X}lo70a~6~_qt@|RHXnOyO>pf?jcyw3?I(mZpWVc$|rjMQ8<2F(CbEn2^{{U~zEE zT?wd|j}@+}L+_dS6{O2*xmqpIesmx}kw{%oj1}Z+nP1n_J3ddy&LJSMQ>;UmcMMXi_(szK|hR*ZZ9MtsMarIUT zv(G2tGbs`Z%wzw!^GmpB@bE9(E1O{#P1YRh)p2VlWpiPYl1P3bCqKooz$fTwcBF07V|4*FS(_K7@V}4lSG8z9|B~!t|DX zHmjUJx(BM*-QR}6kW&JZK6nNe!)<@LQHHhlCkP!DF6Z4$?hQRd34-1*Z8aeBwD@|U z!XiglHeA}x{BcGa!ldM;Stwm_fp4WSrOm|w@N~WI~l_+VSxtm4vBt28F_X7J$ zlPg?Gone6M`CcQ?sCEJt{dOXBxbXQtytJtegW!tJmLeR;(CLBZN)rgwM_Ok#1PieG z$lVTSaqU-b3V5WDxy)ht#ih$S-u&uDV;fGOYzKWT#7MyL{QTw1gSO>1f%+w%@x9Br z$-gTLLj$vDemH&YRIqTg6k3NyceHSVdBhskinelDs!M`5rvjFjmmeR}1LqUyUUcOC z68cKU@7{#&rGz9GBA2@27i~dJhJbtUd$ueOq#&F;cwh|x(MGUKM42nyw+P$O1mZss zj2jdetwEHKbTprl;AH><*#7EBz!h9#!0&w+OIe|Hezzcu%5p#MOHhb7PWpQd@y{BS zzg(GG=T!bEfsC&ysYmMH&dSYfxGkLS@I?@OYDEp6w-e2~>PByZKJh9K$nfZu)zpXq z<%7h^b^Yx>jj%G1dKo3`EmZBa(PUmam@Y?-0P%U%oBY?_g{9KtKwJIK6&=r#?$?hC z%|{qPJ&bgipzVDE*B{~FPx49 z-pu_2Z*DI^@uU?Js^iyTh2(c+86mR<6em=!3%7LPSj!x+xGg7rbb+vmD8S&h!>DkC6xD#YXAJH&_?jdd3ugshr+3VW{#4h#J)!r`qLBx2IXh z7d-DK4F7yY`tdDo`F}^rUVtUvAijHSDwnr?LZ@F=hBEemIf;;8?Ca>51>A5RQlO0i z=s!9-Du8ngc49{A{?G8D2q-NOXFIS-5Wgj&txW;z1!Ufgq4%a#^<&UU-TGl}O}dWb zKh=3;QL3tS;LaY*fRX1yBwnam9Y?i6O@9>Q$41T!=>8{17t%1EY%bpi2q7vSX|%gcGdNdJ(T8A82+v~m$KGhEJK z*xx>ksC@@pDs(}(PuXy9W|P@#`sNo2)bUmnclNhiI{QWIhxZ{F2H5ezOhp<5kraDG zjjROhhDk6A14Ewfu+U~)oTQWmH2`uJxNWAp1-5FC?9&?viEKomN&-U#Vxxv#j3{pa zMn$kIA)$C^pIl@~wacFMot3JonD+@A$rQef^a{lvb;8efdMTVYP`LQ%6!)!wdJW!< zitd?yo(~aJj+0p3>dLp#2x1NW#Y%tK#rc-^9>l&GaL4>>QyDLr$Tx**rN!63NX?gWFS1H_r1AEd)!w%5_wk69w+Q1nVf~mBy1Uezx8j=pK zda*H8ptd3MHPLJ+okjCDa(+g)&lDD#tRT1Wcda`Q7_!pzMN$SZT9mT@0IOJvwg4lB zXvWYtV9`N1p;6<)4%d#o$>`cYrCM^}rCyn;=7D(-$)bRbVLM?}4tbME1jiKf;T*$e z-hP+AJ@ZW7k2@{GF;Uf$#{<Mh|(#qh!o+&XX zJjg6VCm(D3vVQG81X_Z$$7R-!1o@$G<=msE|Ad?}#25^ePa&YTGTb{(W%FqF)p_5%uxUM3RK{RF!3UKSvd7NN{G1E*8)d2EvKr&;LpNTuWP_TDP^hr{P}YmF498%W-MqI z#Np?;9xp~fP%wn6?Ouh;tJypk-FQ=dZ+^Gfl6TopTJO)cVIGX(kHF;gCOPNFPuBEuVTd zWn%nR@|EGiJq2|qB9N9riv#c)HUIc=#ywj+{P8la~>hJ;`sA#Qk1c8HSOUGz+sd|`Q-OUPehC8;zP;G!=wa(zM(0&WCQy@PEkdUSCZBVe*e-~bUdyRk=L;Cj^C-YDFiU9>lQ6wY6!P zjSU}9#0(RHS_*ly_4n`JG6(hc#7KAiu|})qA-a;T={nEk3;wDdxc4Kh4|0^USgyVE zPyPcb$Z$yHz~u?mOEmv*k_TP&JWc5q6;&^^I!Gabu^UN1JOfV7VRiU3NMPfD6arHe z<*tj)#6Nq(`%4~wRXE~f7i2!R`YqGjnkxR_AC{)hpCJ+-I+5q^=^}_vzwG^sjE)&o z2wIWyNjqG~V7vyZa7UNZhv23_;(uRw$oa@fddo;yM}YSP;y@s9?3(Aveq~Nv$lLNa z^AfP5Bp^Cc^aEaFUtgc0?kJ27L?IXEtfQ#GhQxssm7ChX}#1v9aBd`{Ftu$OA7(!49VY`!W9$tu!TQZm;6uJz!(|I^Px?8Xhj;;84;Q zD?!Ub1p2j~p9!LP-`s~Uf-px=bhqJ+3%6xgVzoH0oSoR~o(Rtsx4#>%9gw*dMLJW{r|a1N%kJV`{Znm}Tj zbLHcUQcJC1Y_xZ{j=2`C4EKWVat;r-4yQQ}#mx-TzP&-tyCOa{I_TeFVS1+2`l?ty z?$`tOnnulnm0!F-Li5ZZmk<=$^6s&>5iFFI0ppiGOn-<12i|`MLj$<(z!X^QxTcnz zlJYMf0v0wX)}US81EFEDQ5UhU$BsA{2_bu1d*#Z2LE)dpML&7T;yFviabgIJv2GR9CcLcQKe*juU>{Sibz~nO^->zY-Xwnkr^AxOQeijVP zmyyRkP(*PYPPhJZBH(Oqu0VRzVS(x`KlUc33xwFU2H)+2CaM=YU1)7aO3X)aa@D#Z z%K%bo3N@tj)uH_Yn^W9KwmLvbi0P@WF5<&R2!1t~DIpL&X}}aoyqEDw)?V|y$>j&c zVbjR*)+W0bMyd&FM^cH{UEYj6E4kk^PVcL7l#;8XF$Si5uXoVbP@AP=8{Ed~D+0II zU&+(Z7JW_fTpg&2nlHj(uO++K^u_FJ}?OQLd*;DvPHbdt`sDC_QA9Xf7A^`1ogsWc5jz4Ug|F} z0&gH|8tU7Ns)R3@n()0~=9+_Yun0qX&Cy&yte|TMwde=iAvvC%*^hVaK$!9I%(_{$ zrt(SMt-FG^K}aCMmKqcGD#3%Wx&^au!A{E^%XwPmQzdO}$yA6zC}#j3PXMe z&x}Vi6c-FqE^|T{bd%upApw}jd#ItrXO|HM9Y%-A-AP}2m{~!xDg`Jx%wynX2n!+; za4VSsLdd|LU&?)V0OgW0sN$VvU7$df-(xN&FHa18*7~|7lD7!sA~W-PNIj-aOi-MaCLa-o8Qf*0WczW z+PR`9LOPawoQis8O>2J$PxQ1og^*-mLyG%K$eB9ji7Y|>+31(?41@D!88z1>7%1sGlh4T4131(rw}AFRb=Cz zOkV>kP~^=3@QWeyMo`ca5EK}A6ue(SDEASxb2>Y9kf5aJeIAB=*W)G_6A@M)jvDJV zf6xW3!1Auz8lfl3Jh9ELd|Q7qADqO7m+NesHgW9_FR03@QrVW)&(u{>c;YqaP|83B zv9L`WE)+p3M}Kyyf0AeO_D-GMyC11Xqmaf4@LTr4y#F`2=S;p`dPS)M6&sx6NW};s zVKqM5o>i~ifY>)ALl*<2cofhdE3F(tw%l`RX~3q>A@Ko;fQOk<8b*mYG=(n;63+oK z3XP0>4)6vd&4QnTfY8;>Ta3Y9i6F%RpfRly(`WGF>x!Y(SWJuFgdJ~Gx`bjxJ%io+ zR}bBqY}Y6nB;XhJ^MA4wJ-wMhw&i){uDfa0<`tGeE9?9*8vSvMHBQsg3|G{gY z^p$5xISHkDi#yf%)}j_!TvPNg>k|lih#|i zieM7otUI+vV&=NI1#6Fz51@ALHeANX*oF=M7*stGhw8(4{>eajAtE<~B8FlI)^9`) zlvlYFJy`p`Q`zpmCZwZ%`c!f9e0e&Bj~Ozq2a0jj&RE=OtncVFC=bP`pYVYe4jx|t zNE1l`W?P21%vq;8ot2hNEzZl^pWUqu782#d>cC)eiU`GLyiRi`Kv4qYCD>D0r+!w} z+$;AwcQfvb?}4{PTwnljg)UxaL=_}8q@W+WqaA+{w7823za(#Tl(HLCwSHcmq=yr% zkgNS{T=6)+C@6z?`{2@bt%MgDB{t=n{aQnxK6j=_HQdQtoB7<(@H9j4R|`TBM!lXk zr&LzjqGWr8fdR=pi=e*6NNYX#=*bgZ7IGGxlw^qE z#6UDCV(W&Qck1Z^5*_y>)5 zT8#R?(yV9^@MFnhyiYX6DfvMV(fL;KtL3#j zOdw=Sw_L@<_XDWj?mP<1yo)3NU}OUwi1%Hk%TJB`rmP%sT`wdyLO;){XcpXEaNpTQ zYh>?N>ZUS#M~^8gDOK73j&+G@`XAMok(=Al{u?20IV=PA%+UtM-K*@^rG4!3YgzAt z1vjnwcnFub{YE-Xv#1_rQv zuKyig7)pPfP}a|4##QnwbpsNH?Fj+h0r&>)8>tfv{|1B*IV@V#R3)Er+`}x0MPWe@e2reV=$6eU%V4!-Dra$ z(8b7&Hy-<>%gsJ-6LNgaWxr-f;_)vEn1M0RPh!r;?wS!zCBL+xsl77(m%B|!I9fP> z=^>|v3o9EJ3u!(#$)$0aOBO8t0{`iZ{o&!0_PU6m7mcV)gzyF;HE`0kk1&`6Mq_NjyHW99Vx= zRaJd_U6`@HbifQ12c&Im*eWvS^C$Hn16~H!8qGz5sZiIc&nppW{-tt~*)^2KPjC1S z!gBcI$AkD(eI%p^*0qOMm6q=9PEFZUzaaeMTe+JZ?E@g?EAG5Ggh&!MxO!JhO>Hgv zp`Z+`*Q-g<2CKzau&9B|Y7Na4*u+$ZS*Y<6UJQ6Z!!KTPh^CENjm|8fVAT${qr0@6 zJr}&qooV=)RilXo=PSWe4a(Ycbtm0nH=8FNlF#F}W_FHu1u# ztnxaf_q9_B3)Q4kcjXyWl%fk3^!3@Uw}T%l?)E(jg7077rjXSx@C1oVti=%ytKy4$ zBi4JND4Z!G!hG)&ng%JDAAoeqkU&odMT7b)0N^+HeGSjI@VY(vmroocA?(iU`-77% zMNJwv=h;>Kal4~!0)jo7k%y5(JQF;!tdXn9u0U)^!459svFf>Mk4JQbOy!KYrK^B_ zTP6(4h{?^0iHo#+;nv)tGu5;-T(j@w^Tv2$=G-(&2xt2{2oF)YZ} ztPd5~`uw0TJaK2uG?V#|9uHGg#5~hs+)p&@pb3XY!gmR*d(y=+keXrC*DsXY!Vc8^ zgi2B)2*2nvurY59qn8>`3e^B*rNz?^i6j=--HX#o0r4ej`zHf?p*t}$>H!(o0e3lN zRQs~r;Qst%Q^r$A-cJ#j+Wg2(VD}&DRg&WRalUN=&bTxE(R?JCT32|XM%>}UYvp;9 zEiy(kV!!4_TJ^F9^UOE@GYtedT3RfcHN{(infCYhVVwyo1WJF7VfG>0{CfY3eIwj4MVI2>D znH5lbc8>58U-SNnlZV?cM%qd29sGO>5p+v}YB1fy5k>umzv$@w*HD6hKZZhjsv}+a39~nsGl^VcO-dz7F!+`)LTOp0>U<;qKCw7-?IP z-qAKp#WQ%ELE6M3I|~QP`Y5*D1v{>>T>tKUt&)w2@nhTn#N}k`O!aNnB0dEdpM~;c zjpSTu4fo>r=4E7+(s9{-W?=HegKOAmf)P>=ppUFHz(l29)}>3L8QR?c)R({Vf73Z# zM*x>$*3<6UFIp|A(q%pP*%M9B4&;+=Yo<$4t$d`V z&AbvZ=#>5bxtbJQ&6q#3O@%sfHL;3ytuf;KTbKR&H*4t09I*=w4d3<7iR^CP7vLs{h?HpNX8!Xaik z(39uS;~@?ace zH=oN@zp}SURA>l5I?gOFn9Ml8D!BeRIY=Q616Tk~lTa6p91s@JwV*eLvp{3b9IL|~ zF9)7FRr{?!cUGrWqfJ>)vCgEoySA~e+$K_arT6HACRP_6Q)Goel^0N}^{FAaz#tzZ zZuUa!YrGtfmxmjdIH$yXPoqw-@S*n0X})G&pYHu+b#23uToeL+K~fA3eU!p=DCIF< zL(10Hmfi*6xa;m#J_dUBfDpY#URX+KxGNC)Z|6HAo@-U)fMtd}s+cu?fsNKLykzxs zb@{>4(9dWgZXP)m0prrEPEAud++|n!rt?5U-?Y@1>e_P_^x1Ylzu8z{wl&{1*J~o) zly$Gjd-%ZAX@^;VP{Q_QD$l|qP?m>oR)cqBOT&R@u5uqv1U8KYspkxQ%KVy86?H$> zj+zAe17vf#Ok&OqaMvGVJva5cgH9ink`f6n5f0f6+_B!L$(j?PqmxcToHi!6251I) z$Aa*5W$Z**;$WF_?F!7%gyMmKjH+mp~L$_5@OhMAflT*Oz}S4B%b)c zOR-MkdB`-d@{deUY?!0NlJ1H1m0LKL4w4x=j5MQ}zQh$qVj^{Jjzkqe;j2hIsbhgE zuqNz3g{WpMa(44o-iXwygAdKd-LF`3C;t;tiAL2>vxy4oGhtLe$aw(XHKE}gr=`-f z4w@sVY3W$Sfdxem;9k&GVCU>>tTx>ADa`eD86>QTrSn_8Qqq9JjI<5tpJ63ARtu&hZtUiJOeC$#@xDKkjz> zo3Z3X#?Z&;e{U*j>ZTz4j3ew0(K{Z|VS4Tl|7AtVNcUy@#?AnxToizwZvs}~HNyiuU3A5C%W>x3R%6>WX`1IFK>Se6#`iicK{cA?wzDxoO6ReSZjgoS7h){mX!=M`e zcRP^APlm z0;}AEYp$8x?Dj{U3Fv8d0J6y6p@ZjeIL2zB6<*Vd9UJ2?W$k6Yok~xBY<*pw!;>rW zwDXU&tIiOX+Wap;#m~<#!Z*iyw*TQer^cBp4U83B!t=~VRUU6+4aMfGjK4YQ+dfWNNbj*&kmeX>`+rhNhf+Tkxm0xm;cXb3RGVX{h32GNA00dQTSRmER5Mb zfUPZJeOv#4L(~6~)#TZjV2&J)Git9)o37q>No0xwzcD4b`gK*`7vrW&PBRT`&Y&te zc};FFbLHgd$mIGVc6GJ#133B0tzP{L#OnyUpp)R>4J2})itQFeK`HhIB3P-!d*gi2 zU58eC&t{M}ozER^c)!-cGV~h1kCBY%SvV|>&SxhY2eJVoW+h%f4+QDif^BJ9%gc0Ht;Kmy5eL?)_#AOHk17Bd)sIVL6;D!+B>UTtkO_WBK@ z7tPG((}M$snTj$LNhX~kK-87QW|(YChk7s#YJbbljG6;Gcc&z7Z?;|TJbotgByV=0 zclGx|FSx|85esF8fsrMfa%>Si0&S_BEe9#y5 zXFbRqV+b$OS_wV>4}_$3j?sG%DT?O|9}6b`=l;`BhqaTDH#rr!ZQuVz&;SG}P_? z7DiZKFrxweeZaBvO3 zsJQra9aq=9&+9*LgcD^_iON2~7`UiWZcfvgq0@8(8U#tf&~rTzGO$ec`{_*0LcB{8 zfj>{0FX80Ei47%iBqHVd)9*)N4oHkJop1eN+cihbogWujdvRk9m`=@fkb^=l)l?x&Dg4E^}gSJau?z)q0XbqiwjRT*8P08Y;&AVVlhN%fX@J8E*^-9~AoX{{1ffT{yH-K!z z#J{Vd0KgXML}5y(i$YbZi%UTT2@t~z{d<^yObgXM81v=9`_G@lo;dO=%ng=DGha|- zkt6)~P9v4XN7wa`r<$qfW^T6B6aNS-5uD|NOK9&K=<5#=YZ+Dz2t;Erg^_@NLw%eI z{K^CYl`xWhf9$cyx7~`h@cI2Baq#aq3_o2xM_MBqIZ`t)@~LmgwF>TZg+XRa#H_Ha z+piCAfHxrN1!34p&CpY$gU|5xjj?`;KP3CWpleV6#c7+yfL3@9JrpDYAtLw5-KFwi zTrRiBA@c~(uJ8yvYeZ%Pai-ZPMOFmU8Z%vC=!IGlUV00EUF9f*a*Pa;NR*5d;VNq4 zkWuUt{Q+<&9G39Z@y3V=kocRvG%$(0r;sA!shOKA#h76zNjeg@I*^8};>9{Mg@rBfLuqEWqLF|oBF~Kj|4AIf6>$j(*_`h!+v~=@^~QkxpagJrR|SvjBfoOxR00oU*p)ae+cbSJ7`DDE?8+rJhIAfmoy;-GCl^ z9k9r3AXY?Cuo71FL@(B?a_D8C3PIpKac)2MS*}J?y-O8ZPz=U3Q z)_qek12WVU#}{CEVrClsuB{VL!H%D5V;~6GvVXpLa3Z5QXV2=Iwl>Q>6{jDxBnLu? z@n-wfx(f-=_D8f?E;nC=9rL@J`{T+lIo|IiSIqJ-||p#=)hi*5MY&M$bhN ze~kV7xZ>4z4i0I^n0vp!p5sw!gRpy^J_o!63)~d?^p<5uP!-UvomzN+i(>Kyu!pA_8 z3q{F-FoQkir;6y&7+`sTC}IjCiMYXKHAl-rtK2%Qw`io&`WM2(cm4b^kX?o*eH{j& zn^boL4UdK&WZcsOVA)szUZfAl5n*f^Z4xIGQ>KL^DhDe*-6(2l9Sq6DOFQ#027C{k zwv16o#+3Vv#%eLczK)`br~T6ZmdR{M2_q#)9F7-tKtHldCZ7j2g@Q$su{SXL6~a9l zGRl|gzVpj`0FR(gMt~`L0h{>_C=iq>H9KXN=%yTQs0WCR>;y0+W-0ix zSgB{w1xsz|KiG0}F8O)ago@LY=l)4`Z#L1`Uk&_dj_OqQTbcQy=EHXCU^A$FjcWdm z$AA?mUcspJ5S#%23#T`JeW!|PF+w`1Px;;#K>?*}9tA7`r+e8;$Trlc?-n{XGsc*H z27Q)ki`CU7qMo?Fi0T5ARE?x>3k-ott$wuZ+qp8?(#v3Yg84{91nP|8-ew|QKt1!} z%8=mmtX<17=GxiWIo%FMws9PP)WA^Y8)m;a4k98S+*%x(o0|_drA-G+%ZMu*#PJQ@ z1=!~RQ1H0GsrJr=LR0j`lJWclMBT|0!jhNGQ&3f15I|Ku$f7{&^CkK7%YRt)J&g|p z6b@d28hS~2U$Tm4f$)c($T)Vvuj|}W>lfX3)R!cc8snpTNweq}GT68XZr8C#(j;4h z#SEM=a0sMfsCS#Ak70hFw~!s!bT2(VXGh* zQFVavVYfkfnlb0sN^}f`E3pcZ<1=vXzzWl+rp?O5MF|KXqr<&rE5mZq{x`h8^L6N? zWWjh?G?^4b=j*$4Ot_Pj2@rS+CqT{7j%ql#;USf}_g5kG^C`#wRQYuCP~L-c%Ti9y zN6Qq{KV9@3FW)a+;Z6}46zH-9)cF99hCyLc`9 z)Me%6S$9NtuPS0X-uQUs@&;4STjolXIf0u|L(~v-WhBGTf$=vC1bzryycP_>B~Mq* zbs%cZxA#G8>wxKjanmc&9q^kRv1E|Bas8HNhD(j)VL_ejfh32|MbZ;Vsf(jE7>=KLCyl1KaT-7)f|;wX8-X zubWV<4FQ-3mt7t9dU*fS6(%c>eVcg{eP}o_!Z}Ze8sY<3)u5qK;)z}h{46W678nwf zRI4cAy}5}~i*M<8{k*gY3>n*xB$Y-N1)#Sb8<7k*JrQcJY?0cNB$9xF>qiN>*Tiy)Z8ew$QBQP zvY(BeX372VYkVwGu(2LURW1&b1gt?%d>b{NGZlZBmR~s%PI#|;x zZ=x*p1M*vmLloK=P z0UweTv3}4V75HiRR1i>xL}ylTrN0IWDyN1-S=ioUi6DJ9u(wZLo^mBK7=5^Ug!xKD zkgaImKzIgLFQMo(@(+i*<9jFwf-)Dwzj!G?iJ(L1B%Ie+vT|iOUT`!@lM;05K+0I} z$*x^^)LdcOo5S~-!+nC?7Qns>iShG;Ymkqe1BB!0X+)oN8Qc=;NQ;uDK=#wGVKru_ zToPbcsA-U0cG)?O~_3UZ@Ja9-o)5)NN_k4P$BApwQt zI14hrD|7Nkb4!o1us_i`5#!hgR#+SVU!OoHwXu!jG)ysVOg~CeFgz6X4KR*ES*12= zL2p&pJPxlkD089X%mUGOt9aJJY-(LHdE5lLfO84YjoW|%k?-{m4n7D@)S?h~{>_%Dya_z(*;DaD3C#%*qmH5G z_}}Q+;9zV$Xm*$?0oSG&QPA}<3uY_Z?hm~7^KT4)&_L;T@5*hcrb9$9gsn}|T$;Io zraWy0#MSf0>AJOB={ijlHgij(ac}xZP;AKlEpM!PIvGq1Alh;(R^&9CV}c1oNG8HE zmCb0>r3C5FEw*Z0;c*dz^Z^UUVP{n9mFi15cyGuxz+ty`_z?L*Z*< zwU!xII?DO?KtIppXSq= z`jqo;wBy+Mj5eC>m#I89W^&+?@_0tBs?lC+snddIHtwjtl`i{1vU=(Dq8ZouJH^a| zt0YcMpP%WbqagIxM&aUhVu^|csgEUpYkAD}_EJiD>uVErUaDb_u$|WZ(XU*O;89CI zReo6dCWVKGcfi{YC_K;`{o2}EztKkwM)##J+NoKId_v}CKxxqBR#j6gEH1u^oNK8% z$9tt6&(+6g{p{JZy+O~gtvHPc)8KgM&~gkf-D7Lp05j>YTm=S0>g=STc|1eN92E7V zt3a25DrX5sx;0?Qx)fPm@z>&yas&eaeNrR%>O(>Gb;06`!o0#?~nzYUsqde2&*z>wiFR-Fo?a^5~3-|3z?I;m#1Our-uAgxQ>73JjQN}2xX;G%~V2ji!_yu7E+ zo=Jb&auqVa{T?2wmU-3~h{@;{y2E2k(@8xGw)>@qhK40DFy0m+J#k#>6E#l3trOVP zjW20vXn5Ft`22gvgd`re<`0=2Co66T)QxL!uY6hPir*FwrXASG?e~w4O3x|xJo5A6|QQV1}R|???MIMz^*Dk5B#=2A^=jy?e1VdIHi_L`(0{ zK^r{G4Fhu-sXK6aN_?W-%WTWMknP6;B1?t4UB1H4PAvci$G?> ze|L4+_KN)TgBmm)=~yP{;BhDnht&W|Fa+dvRYRrlU3(?_Z;1vk-;|oJYD;< F{{{24swDsb diff --git a/public/images/api/qiskit/dev/visualization-6.png b/public/images/api/qiskit/dev/visualization-6.png index 71bd0e77858bc39f26c9e6e240062b32e26fc044..1e03672a927119872d19f42efb2f6c3df95a52cf 100644 GIT binary patch literal 113083 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 z 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 z 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 literal 113145 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 F{{{24swDsb diff --git a/scripts/api-html-artifacts.json b/scripts/api-html-artifacts.json index fca32317b61..0d15120abff 100644 --- a/scripts/api-html-artifacts.json +++ b/scripts/api-html-artifacts.json @@ -1,6 +1,7 @@ { "qiskit": { - "dev": "https://ibm.box.com/shared/static/eh9tzx3senx5xkq1vvtsr5h697r6j7gk.zip", + "dev": "https://ibm.box.com/shared/static/gtaceb0qjssbl3gl0h3idi9fjjdv0x9e.zip", + "1.0": "", "0.46": "https://ibm.box.com/shared/static/74ppfh7b3rx73fntmk9p8pw4asf6pp4a.zip", "0.45": "https://ibm.box.com/shared/static/e2rwbrztml4dg6lkk1w3e0kmevkw9w7s.zip", "0.44": "https://ibm.box.com/shared/static/myfk3g20xsp5xj8f3f1fd81p7ywgl7an.zip", From 1f3d4406421c77dc62ff12077235ce1b7db0335e Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Wed, 14 Feb 2024 17:15:13 -0500 Subject: [PATCH 2/3] npm run make-historical -- -p qiskit --- docs/api/qiskit/0.46/_package.json | 4 + docs/api/qiskit/0.46/_toc.json | 3633 +++++++++++++++ docs/api/qiskit/0.46/algorithms.md | 279 ++ docs/api/qiskit/0.46/assembler.md | 186 + docs/api/qiskit/0.46/circuit.md | 357 ++ docs/api/qiskit/0.46/circuit_classical.md | 974 ++++ docs/api/qiskit/0.46/circuit_library.md | 1292 ++++++ docs/api/qiskit/0.46/circuit_singleton.md | 210 + docs/api/qiskit/0.46/classicalfunction.md | 84 + docs/api/qiskit/0.46/compiler.md | 310 ++ docs/api/qiskit/0.46/converters.md | 310 ++ docs/api/qiskit/0.46/dagcircuit.md | 54 + docs/api/qiskit/0.46/exceptions.md | 72 + docs/api/qiskit/0.46/execute.md | 183 + docs/api/qiskit/0.46/extensions.md | 50 + docs/api/qiskit/0.46/index.md | 64 + docs/api/qiskit/0.46/opflow.md | 214 + docs/api/qiskit/0.46/passmanager.md | 173 + docs/api/qiskit/0.46/primitives.md | 146 + docs/api/qiskit/0.46/providers.md | 509 +++ .../qiskit/0.46/providers_basic_provider.md | 52 + docs/api/qiskit/0.46/providers_basicaer.md | 58 + .../qiskit/0.46/providers_fake_provider.md | 265 ++ docs/api/qiskit/0.46/providers_models.md | 39 + docs/api/qiskit/0.46/pulse.md | 2798 ++++++++++++ docs/api/qiskit/0.46/qasm.md | 54 + docs/api/qiskit/0.46/qasm2.md | 539 +++ docs/api/qiskit/0.46/qasm3.md | 299 ++ .../0.46/qiskit.algorithms.AlgorithmJob.md | 168 + .../qiskit.algorithms.AmplificationProblem.md | 93 + .../qiskit.algorithms.AmplitudeAmplifier.md | 40 + .../qiskit.algorithms.AmplitudeEstimation.md | 209 + ...it.algorithms.AmplitudeEstimationResult.md | 124 + .../qiskit.algorithms.AmplitudeEstimator.md | 36 + ...kit.algorithms.AmplitudeEstimatorResult.md | 82 + .../0.46/qiskit.algorithms.Eigensolver.md | 65 + .../qiskit.algorithms.EigensolverResult.md | 60 + .../qiskit.algorithms.EstimationProblem.md | 116 + .../qiskit.algorithms.EvolutionProblem.md | 62 + .../0.46/qiskit.algorithms.EvolutionResult.md | 43 + ...it.algorithms.FasterAmplitudeEstimation.md | 129 + ...orithms.FasterAmplitudeEstimationResult.md | 106 + .../qiskit/0.46/qiskit.algorithms.Grover.md | 196 + .../0.46/qiskit.algorithms.GroverResult.md | 86 + ...t.algorithms.HamiltonianPhaseEstimation.md | 90 + ...rithms.HamiltonianPhaseEstimationResult.md | 92 + .../qiskit.algorithms.ImaginaryEvolver.md | 48 + .../qiskit.algorithms.ImaginaryTimeEvolver.md | 42 + ...algorithms.IterativeAmplitudeEstimation.md | 141 + ...thms.IterativeAmplitudeEstimationResult.md | 130 + ...kit.algorithms.IterativePhaseEstimation.md | 92 + ...ms.MaximumLikelihoodAmplitudeEstimation.md | 175 + ...imumLikelihoodAmplitudeEstimationResult.md | 112 + .../qiskit.algorithms.MinimumEigensolver.md | 67 + ...kit.algorithms.MinimumEigensolverResult.md | 60 + .../qiskit.algorithms.NumPyEigensolver.md | 88 + ...skit.algorithms.NumPyMinimumEigensolver.md | 77 + .../api/qiskit/0.46/qiskit.algorithms.PVQD.md | 232 + .../0.46/qiskit.algorithms.PVQDResult.md | 42 + .../0.46/qiskit.algorithms.PhaseEstimation.md | 128 + ...qiskit.algorithms.PhaseEstimationResult.md | 103 + .../qiskit.algorithms.PhaseEstimationScale.md | 116 + .../api/qiskit/0.46/qiskit.algorithms.QAOA.md | 252 ++ .../0.46/qiskit.algorithms.RealEvolver.md | 48 + .../0.46/qiskit.algorithms.RealTimeEvolver.md | 42 + ...qiskit.algorithms.SciPyImaginaryEvolver.md | 52 + .../qiskit.algorithms.SciPyRealEvolver.md | 52 + .../qiskit.algorithms.TimeEvolutionProblem.md | 116 + .../qiskit.algorithms.TimeEvolutionResult.md | 79 + .../0.46/qiskit.algorithms.TrotterQRTE.md | 120 + docs/api/qiskit/0.46/qiskit.algorithms.VQD.md | 243 + .../0.46/qiskit.algorithms.VQDResult.md | 108 + docs/api/qiskit/0.46/qiskit.algorithms.VQE.md | 270 ++ .../qiskit/0.46/qiskit.algorithms.VarQITE.md | 56 + .../qiskit/0.46/qiskit.algorithms.VarQRTE.md | 56 + ...kit.algorithms.eigensolvers.Eigensolver.md | 61 + ...gorithms.eigensolvers.EigensolverResult.md | 48 + ...lgorithms.eigensolvers.NumPyEigensolver.md | 84 + ...hms.eigensolvers.NumPyEigensolverResult.md | 54 + .../qiskit.algorithms.eigensolvers.VQD.md | 173 + ...iskit.algorithms.eigensolvers.VQDResult.md | 90 + .../0.46/qiskit.algorithms.eigensolvers.md | 38 + ...orithms.gradients.BaseEstimatorGradient.md | 98 + .../qiskit.algorithms.gradients.BaseQGT.md | 115 + ...lgorithms.gradients.BaseSamplerGradient.md | 76 + ...ithms.gradients.EstimatorGradientResult.md | 44 + ...s.gradients.FiniteDiffEstimatorGradient.md | 107 + ...hms.gradients.FiniteDiffSamplerGradient.md | 96 + ...thms.gradients.LinCombEstimatorGradient.md | 104 + .../qiskit.algorithms.gradients.LinCombQGT.md | 124 + ...rithms.gradients.LinCombSamplerGradient.md | 84 + ...s.gradients.ParamShiftEstimatorGradient.md | 106 + ...hms.gradients.ParamShiftSamplerGradient.md | 84 + .../0.46/qiskit.algorithms.gradients.QFI.md | 77 + .../qiskit.algorithms.gradients.QFIResult.md | 44 + .../qiskit.algorithms.gradients.QGTResult.md | 52 + ...thms.gradients.ReverseEstimatorGradient.md | 104 + .../qiskit.algorithms.gradients.ReverseQGT.md | 100 + ...orithms.gradients.SPSAEstimatorGradient.md | 96 + ...lgorithms.gradients.SPSASamplerGradient.md | 85 + ...orithms.gradients.SamplerGradientResult.md | 44 + .../0.46/qiskit.algorithms.gradients.md | 76 + ...lgorithms.minimum_eigensolvers.AdaptVQE.md | 143 + ...hms.minimum_eigensolvers.AdaptVQEResult.md | 122 + ...minimum_eigensolvers.MinimumEigensolver.md | 61 + ...m_eigensolvers.MinimumEigensolverResult.md | 48 + ...um_eigensolvers.NumPyMinimumEigensolver.md | 71 + ...ensolvers.NumPyMinimumEigensolverResult.md | 54 + ...it.algorithms.minimum_eigensolvers.QAOA.md | 172 + ...eigensolvers.SamplingMinimumEigensolver.md | 59 + ...olvers.SamplingMinimumEigensolverResult.md | 66 + ...rithms.minimum_eigensolvers.SamplingVQE.md | 168 + ....minimum_eigensolvers.SamplingVQEResult.md | 112 + ...kit.algorithms.minimum_eigensolvers.VQE.md | 172 + ...gorithms.minimum_eigensolvers.VQEResult.md | 96 + .../qiskit.algorithms.minimum_eigensolvers.md | 43 + .../0.46/qiskit.algorithms.optimizers.ADAM.md | 282 ++ .../0.46/qiskit.algorithms.optimizers.AQGD.md | 241 + .../qiskit.algorithms.optimizers.AskData.md | 43 + .../qiskit.algorithms.optimizers.BOBYQA.md | 221 + .../0.46/qiskit.algorithms.optimizers.CG.md | 224 + .../qiskit.algorithms.optimizers.COBYLA.md | 222 + .../0.46/qiskit.algorithms.optimizers.CRS.md | 233 + .../qiskit.algorithms.optimizers.DIRECT_L.md | 235 + ...kit.algorithms.optimizers.DIRECT_L_RAND.md | 235 + .../0.46/qiskit.algorithms.optimizers.ESCH.md | 235 + .../0.46/qiskit.algorithms.optimizers.GSLS.md | 342 ++ ...t.algorithms.optimizers.GradientDescent.md | 466 ++ ...orithms.optimizers.GradientDescentState.md | 88 + .../qiskit.algorithms.optimizers.IMFIL.md | 221 + .../qiskit.algorithms.optimizers.ISRES.md | 233 + .../qiskit.algorithms.optimizers.L_BFGS_B.md | 230 + .../qiskit.algorithms.optimizers.Minimizer.md | 40 + ...iskit.algorithms.optimizers.NELDER_MEAD.md | 228 + .../0.46/qiskit.algorithms.optimizers.NFT.md | 232 + .../qiskit.algorithms.optimizers.Optimizer.md | 221 + ...t.algorithms.optimizers.OptimizerResult.md | 70 + ...it.algorithms.optimizers.OptimizerState.md | 70 + ...rithms.optimizers.OptimizerSupportLevel.md | 44 + .../qiskit.algorithms.optimizers.POWELL.md | 223 + .../qiskit.algorithms.optimizers.P_BFGS.md | 225 + .../qiskit.algorithms.optimizers.QNSPSA.md | 416 ++ .../qiskit.algorithms.optimizers.SLSQP.md | 226 + .../qiskit.algorithms.optimizers.SNOBFIT.md | 225 + .../0.46/qiskit.algorithms.optimizers.SPSA.md | 399 ++ ...it.algorithms.optimizers.SciPyOptimizer.md | 218 + ...lgorithms.optimizers.SteppableOptimizer.md | 396 ++ .../0.46/qiskit.algorithms.optimizers.TNC.md | 227 + .../qiskit.algorithms.optimizers.TellData.md | 41 + .../0.46/qiskit.algorithms.optimizers.UMDA.md | 307 ++ .../0.46/qiskit.algorithms.optimizers.md | 97 + ...optimizers.optimizer_utils.LearningRate.md | 56 + ...t.algorithms.optimizers.optimizer_utils.md | 28 + ...thms.state_fidelities.BaseStateFidelity.md | 71 + ...ithms.state_fidelities.ComputeUncompute.md | 117 + ...ms.state_fidelities.StateFidelityResult.md | 52 + .../qiskit.algorithms.state_fidelities.md | 35 + ...ime_evolvers.trotterization.TrotterQRTE.md | 109 + ...algorithms.time_evolvers.trotterization.md | 22 + ...evolvers.variational.ForwardEulerSolver.md | 42 + ...variational.ImaginaryMcLachlanPrinciple.md | 56 + ...riational.ImaginaryVariationalPrinciple.md | 23 + ...vers.variational.RealMcLachlanPrinciple.md | 56 + ...rs.variational.RealVariationalPrinciple.md | 23 + ...olvers.variational.VariationalPrinciple.md | 93 + ...it.algorithms.time_evolvers.variational.md | 78 + .../qiskit/0.46/qiskit.assembler.RunConfig.md | 106 + .../0.46/qiskit.circuit.AncillaQubit.md | 55 + .../0.46/qiskit.circuit.AncillaRegister.md | 90 + .../0.46/qiskit.circuit.AnnotatedOperation.md | 84 + docs/api/qiskit/0.46/qiskit.circuit.Bit.md | 50 + .../qiskit/0.46/qiskit.circuit.BreakLoopOp.md | 345 ++ .../0.46/qiskit.circuit.CircuitInstruction.md | 82 + .../0.46/qiskit.circuit.ClassicalRegister.md | 90 + docs/api/qiskit/0.46/qiskit.circuit.Clbit.md | 55 + .../0.46/qiskit.circuit.CommutationChecker.md | 46 + .../0.46/qiskit.circuit.ContinueLoopOp.md | 349 ++ .../0.46/qiskit.circuit.ControlFlowOp.md | 353 ++ .../0.46/qiskit.circuit.ControlModifier.md | 36 + .../0.46/qiskit.circuit.ControlledGate.md | 495 +++ docs/api/qiskit/0.46/qiskit.circuit.Delay.md | 350 ++ .../0.46/qiskit.circuit.EquivalenceLibrary.md | 184 + .../qiskit/0.46/qiskit.circuit.ForLoopOp.md | 366 ++ docs/api/qiskit/0.46/qiskit.circuit.Gate.md | 427 ++ .../qiskit/0.46/qiskit.circuit.IfElseOp.md | 378 ++ .../qiskit/0.46/qiskit.circuit.Instruction.md | 331 ++ .../0.46/qiskit.circuit.InstructionSet.md | 121 + .../0.46/qiskit.circuit.InverseModifier.md | 18 + .../qiskit/0.46/qiskit.circuit.Operation.md | 55 + .../qiskit/0.46/qiskit.circuit.Parameter.md | 258 ++ .../qiskit.circuit.ParameterExpression.md | 250 ++ .../0.46/qiskit.circuit.ParameterVector.md | 52 + .../0.46/qiskit.circuit.PowerModifier.md | 26 + .../0.46/qiskit.circuit.QuantumCircuit.md | 3922 +++++++++++++++++ .../0.46/qiskit.circuit.QuantumRegister.md | 90 + docs/api/qiskit/0.46/qiskit.circuit.Qubit.md | 55 + .../qiskit/0.46/qiskit.circuit.Register.md | 88 + .../0.46/qiskit.circuit.SwitchCaseOp.md | 392 ++ .../qiskit/0.46/qiskit.circuit.WhileLoopOp.md | 367 ++ ...uit.classicalfunction.BooleanExpression.md | 487 ++ ...uit.classicalfunction.ClassicalFunction.md | 544 +++ ...tion.ClassicalFunctionCompilerTypeError.md | 20 + ...calfunction.ClassicalFunctionParseError.md | 20 + .../qiskit/0.46/qiskit.circuit.library.AND.md | 227 + .../0.46/qiskit.circuit.library.Barrier.md | 311 ++ .../0.46/qiskit.circuit.library.C3SXGate.md | 176 + .../0.46/qiskit.circuit.library.C3XGate.md | 187 + .../0.46/qiskit.circuit.library.C4XGate.md | 191 + .../0.46/qiskit.circuit.library.CCXGate.md | 243 + .../0.46/qiskit.circuit.library.CCZGate.md | 196 + ...it.circuit.library.CDKMRippleCarryAdder.md | 283 ++ .../0.46/qiskit.circuit.library.CHGate.md | 211 + .../0.46/qiskit.circuit.library.CPhaseGate.md | 222 + .../0.46/qiskit.circuit.library.CRXGate.md | 213 + .../0.46/qiskit.circuit.library.CRYGate.md | 213 + .../0.46/qiskit.circuit.library.CRZGate.md | 215 + .../0.46/qiskit.circuit.library.CSGate.md | 195 + .../0.46/qiskit.circuit.library.CSXGate.md | 199 + .../0.46/qiskit.circuit.library.CSdgGate.md | 195 + .../0.46/qiskit.circuit.library.CSwapGate.md | 230 + .../0.46/qiskit.circuit.library.CU1Gate.md | 212 + .../0.46/qiskit.circuit.library.CU3Gate.md | 217 + .../0.46/qiskit.circuit.library.CUGate.md | 207 + .../0.46/qiskit.circuit.library.CXGate.md | 239 + .../0.46/qiskit.circuit.library.CYGate.md | 209 + .../0.46/qiskit.circuit.library.CZGate.md | 190 + .../0.46/qiskit.circuit.library.DCXGate.md | 141 + .../0.46/qiskit.circuit.library.Diagonal.md | 255 ++ .../qiskit.circuit.library.DiagonalGate.md | 137 + .../qiskit.circuit.library.DraperQFTAdder.md | 254 ++ .../0.46/qiskit.circuit.library.ECRGate.md | 175 + .../qiskit.circuit.library.EfficientSU2.md | 351 ++ ...t.circuit.library.EvolvedOperatorAnsatz.md | 319 ++ .../qiskit.circuit.library.ExactReciprocal.md | 224 + ...it.circuit.library.ExcitationPreserving.md | 370 ++ .../qiskit.circuit.library.FourierChecking.md | 238 + ...ircuit.library.FunctionalPauliRotations.md | 188 + .../qiskit/0.46/qiskit.circuit.library.GMS.md | 247 ++ .../qiskit/0.46/qiskit.circuit.library.GR.md | 241 + .../qiskit/0.46/qiskit.circuit.library.GRX.md | 240 + .../qiskit/0.46/qiskit.circuit.library.GRY.md | 240 + .../qiskit/0.46/qiskit.circuit.library.GRZ.md | 240 + .../qiskit.circuit.library.GlobalPhaseGate.md | 145 + .../0.46/qiskit.circuit.library.GraphState.md | 245 + .../qiskit.circuit.library.GroverOperator.md | 380 ++ .../0.46/qiskit.circuit.library.HGate.md | 173 + ...circuit.library.HRSCumulativeMultiplier.md | 277 ++ .../qiskit.circuit.library.HamiltonianGate.md | 181 + ...it.circuit.library.HiddenLinearFunction.md | 247 ++ .../0.46/qiskit.circuit.library.IGate.md | 156 + .../qiskit/0.46/qiskit.circuit.library.IQP.md | 235 + .../0.46/qiskit.circuit.library.Initialize.md | 170 + .../qiskit.circuit.library.InnerProduct.md | 246 ++ ...iskit.circuit.library.IntegerComparator.md | 201 + .../0.46/qiskit.circuit.library.Isometry.md | 174 + ...circuit.library.LinearAmplitudeFunction.md | 283 ++ .../qiskit.circuit.library.LinearFunction.md | 251 ++ ...it.circuit.library.LinearPauliRotations.md | 235 + .../0.46/qiskit.circuit.library.MCMT.md | 263 ++ .../0.46/qiskit.circuit.library.MCMTVChain.md | 279 ++ .../qiskit.circuit.library.MCPhaseGate.md | 206 + .../0.46/qiskit.circuit.library.MCXGate.md | 207 + .../qiskit.circuit.library.MCXGrayCode.md | 171 + .../qiskit.circuit.library.MCXRecursive.md | 179 + .../0.46/qiskit.circuit.library.MCXVChain.md | 177 + .../0.46/qiskit.circuit.library.MSGate.md | 123 + .../0.46/qiskit.circuit.library.Measure.md | 316 ++ .../0.46/qiskit.circuit.library.NLocal.md | 462 ++ .../qiskit/0.46/qiskit.circuit.library.OR.md | 227 + ...skit.circuit.library.PauliEvolutionGate.md | 191 + .../qiskit.circuit.library.PauliFeatureMap.md | 418 ++ .../0.46/qiskit.circuit.library.PauliGate.md | 148 + .../qiskit.circuit.library.PauliTwoDesign.md | 329 ++ .../qiskit.circuit.library.Permutation.md | 229 + .../qiskit.circuit.library.PermutationGate.md | 157 + .../qiskit.circuit.library.PhaseEstimation.md | 246 ++ .../0.46/qiskit.circuit.library.PhaseGate.md | 203 + .../qiskit.circuit.library.PhaseOracle.md | 283 ++ ...skit.circuit.library.PiecewiseChebyshev.md | 241 + ...t.library.PiecewiseLinearPauliRotations.md | 278 ++ ...brary.PiecewisePolynomialPauliRotations.md | 310 ++ ...ircuit.library.PolynomialPauliRotations.md | 238 + .../0.46/qiskit.circuit.library.QAOAAnsatz.md | 345 ++ .../qiskit/0.46/qiskit.circuit.library.QFT.md | 249 ++ .../qiskit.circuit.library.QuadraticForm.md | 272 ++ .../qiskit.circuit.library.QuantumVolume.md | 234 + .../0.46/qiskit.circuit.library.RC3XGate.md | 123 + .../0.46/qiskit.circuit.library.RCCXGate.md | 123 + .../qiskit.circuit.library.RGQFTMultiplier.md | 256 ++ .../0.46/qiskit.circuit.library.RGate.md | 159 + .../0.46/qiskit.circuit.library.RVGate.md | 166 + .../0.46/qiskit.circuit.library.RXGate.md | 181 + .../0.46/qiskit.circuit.library.RXXGate.md | 183 + .../0.46/qiskit.circuit.library.RYGate.md | 181 + .../0.46/qiskit.circuit.library.RYYGate.md | 183 + .../0.46/qiskit.circuit.library.RZGate.md | 191 + .../0.46/qiskit.circuit.library.RZXGate.md | 223 + .../0.46/qiskit.circuit.library.RZZGate.md | 195 + .../qiskit.circuit.library.RealAmplitudes.md | 389 ++ .../0.46/qiskit.circuit.library.Reset.md | 316 ++ .../0.46/qiskit.circuit.library.SGate.md | 160 + .../0.46/qiskit.circuit.library.SXGate.md | 182 + .../0.46/qiskit.circuit.library.SXdgGate.md | 148 + .../0.46/qiskit.circuit.library.SdgGate.md | 160 + ...qiskit.circuit.library.StatePreparation.md | 211 + .../0.46/qiskit.circuit.library.SwapGate.md | 181 + .../0.46/qiskit.circuit.library.TGate.md | 160 + .../0.46/qiskit.circuit.library.TdgGate.md | 160 + .../0.46/qiskit.circuit.library.TwoLocal.md | 415 ++ .../0.46/qiskit.circuit.library.U1Gate.md | 208 + .../0.46/qiskit.circuit.library.U2Gate.md | 187 + .../0.46/qiskit.circuit.library.U3Gate.md | 204 + .../0.46/qiskit.circuit.library.UCGate.md | 169 + .../qiskit.circuit.library.UCPauliRotGate.md | 122 + .../0.46/qiskit.circuit.library.UCRXGate.md | 121 + .../0.46/qiskit.circuit.library.UCRYGate.md | 121 + .../0.46/qiskit.circuit.library.UCRZGate.md | 121 + .../0.46/qiskit.circuit.library.UGate.md | 187 + .../qiskit.circuit.library.UnitaryGate.md | 209 + .../qiskit.circuit.library.UnitaryOverlap.md | 256 ++ ...kit.circuit.library.VBERippleCarryAdder.md | 255 ++ .../qiskit.circuit.library.WeightedAdder.md | 251 ++ .../0.46/qiskit.circuit.library.XGate.md | 191 + .../qiskit/0.46/qiskit.circuit.library.XOR.md | 229 + .../qiskit.circuit.library.XXMinusYYGate.md | 193 + .../qiskit.circuit.library.XXPlusYYGate.md | 193 + .../0.46/qiskit.circuit.library.YGate.md | 191 + .../qiskit.circuit.library.ZFeatureMap.md | 367 ++ .../0.46/qiskit.circuit.library.ZGate.md | 199 + .../qiskit.circuit.library.ZZFeatureMap.md | 372 ++ .../0.46/qiskit.circuit.library.iSwapGate.md | 180 + .../0.46/qiskit.dagcircuit.DAGCircuit.md | 1026 +++++ .../0.46/qiskit.dagcircuit.DAGDepNode.md | 117 + .../0.46/qiskit.dagcircuit.DAGDependency.md | 390 ++ .../0.46/qiskit.dagcircuit.DAGInNode.md | 55 + .../qiskit/0.46/qiskit.dagcircuit.DAGNode.md | 45 + .../0.46/qiskit.dagcircuit.DAGOpNode.md | 69 + .../0.46/qiskit.dagcircuit.DAGOutNode.md | 55 + .../qiskit.extensions.SingleQubitUnitary.md | 424 ++ .../qiskit/0.46/qiskit.extensions.Snapshot.md | 322 ++ .../qiskit/0.46/qiskit.opflow.OperatorBase.md | 420 ++ ...qiskit.opflow.converters.AbelianGrouper.md | 74 + ...qiskit.opflow.converters.CircuitSampler.md | 108 + .../qiskit.opflow.converters.ConverterBase.md | 44 + ...skit.opflow.converters.DictToCircuitSum.md | 50 + ...skit.opflow.converters.PauliBasisChange.md | 268 ++ ...kit.opflow.converters.TwoQubitReduction.md | 50 + .../qiskit/0.46/qiskit.opflow.converters.md | 52 + .../qiskit.opflow.evolutions.EvolutionBase.md | 44 + ...skit.opflow.evolutions.EvolutionFactory.md | 48 + .../qiskit.opflow.evolutions.EvolvedOp.md | 337 ++ ...iskit.opflow.evolutions.MatrixEvolution.md | 44 + ...opflow.evolutions.PauliTrotterEvolution.md | 96 + .../0.46/qiskit.opflow.evolutions.QDrift.md | 60 + .../0.46/qiskit.opflow.evolutions.Suzuki.md | 69 + .../0.46/qiskit.opflow.evolutions.Trotter.md | 40 + ...it.opflow.evolutions.TrotterizationBase.md | 56 + ...opflow.evolutions.TrotterizationFactory.md | 49 + .../qiskit/0.46/qiskit.opflow.evolutions.md | 61 + ...opflow.expectations.AerPauliExpectation.md | 64 + ...kit.opflow.expectations.CVaRExpectation.md | 89 + ...kit.opflow.expectations.ExpectationBase.md | 64 + ....opflow.expectations.ExpectationFactory.md | 50 + ...t.opflow.expectations.MatrixExpectation.md | 64 + ...it.opflow.expectations.PauliExpectation.md | 68 + .../qiskit/0.46/qiskit.opflow.expectations.md | 46 + ...qiskit.opflow.gradients.CircuitGradient.md | 53 + .../qiskit.opflow.gradients.CircuitQFI.md | 53 + .../qiskit.opflow.gradients.DerivativeBase.md | 102 + .../0.46/qiskit.opflow.gradients.Gradient.md | 90 + .../qiskit.opflow.gradients.GradientBase.md | 45 + .../0.46/qiskit.opflow.gradients.Hessian.md | 87 + .../qiskit.opflow.gradients.HessianBase.md | 43 + ...qiskit.opflow.gradients.NaturalGradient.md | 119 + .../0.46/qiskit.opflow.gradients.QFI.md | 66 + .../0.46/qiskit.opflow.gradients.QFIBase.md | 48 + .../qiskit/0.46/qiskit.opflow.gradients.md | 132 + .../0.46/qiskit.opflow.list_ops.ComposedOp.md | 254 ++ .../0.46/qiskit.opflow.list_ops.ListOp.md | 518 +++ .../0.46/qiskit.opflow.list_ops.SummedOp.md | 253 ++ .../0.46/qiskit.opflow.list_ops.TensoredOp.md | 218 + .../api/qiskit/0.46/qiskit.opflow.list_ops.md | 54 + .../qiskit.opflow.primitive_ops.CircuitOp.md | 338 ++ .../qiskit.opflow.primitive_ops.MatrixOp.md | 306 ++ .../qiskit.opflow.primitive_ops.PauliOp.md | 337 ++ .../qiskit.opflow.primitive_ops.PauliSumOp.md | 449 ++ ...qiskit.opflow.primitive_ops.PrimitiveOp.md | 429 ++ ....opflow.primitive_ops.TaperedPauliSumOp.md | 130 + ...iskit.opflow.primitive_ops.Z2Symmetries.md | 220 + .../0.46/qiskit.opflow.primitive_ops.md | 51 + ...qiskit.opflow.state_fns.CVaRMeasurement.md | 352 ++ .../qiskit.opflow.state_fns.CircuitStateFn.md | 375 ++ .../qiskit.opflow.state_fns.DictStateFn.md | 307 ++ ...qiskit.opflow.state_fns.OperatorStateFn.md | 272 ++ ...it.opflow.state_fns.SparseVectorStateFn.md | 281 ++ .../0.46/qiskit.opflow.state_fns.StateFn.md | 461 ++ .../qiskit.opflow.state_fns.VectorStateFn.md | 306 ++ .../qiskit/0.46/qiskit.opflow.state_fns.md | 50 + .../0.46/qiskit.passmanager.BaseController.md | 73 + .../qiskit.passmanager.BasePassManager.md | 141 + ...iskit.passmanager.ConditionalController.md | 95 + .../qiskit.passmanager.DoWhileController.md | 97 + .../0.46/qiskit.passmanager.FlowController.md | 168 + ...qiskit.passmanager.FlowControllerLinear.md | 95 + .../0.46/qiskit.passmanager.GenericPass.md | 97 + .../qiskit.passmanager.PassManagerState.md | 40 + .../0.46/qiskit.passmanager.PropertySet.md | 102 + .../0.46/qiskit.passmanager.WorkflowStatus.md | 50 + .../qiskit.primitives.BackendEstimator.md | 172 + .../0.46/qiskit.primitives.BackendSampler.md | 153 + .../0.46/qiskit.primitives.BaseEstimator.md | 132 + .../0.46/qiskit.primitives.BaseSampler.md | 96 + .../0.46/qiskit.primitives.Estimator.md | 137 + .../0.46/qiskit.primitives.EstimatorResult.md | 81 + .../qiskit/0.46/qiskit.primitives.Sampler.md | 105 + .../0.46/qiskit.primitives.SamplerResult.md | 81 + .../qiskit/0.46/qiskit.providers.Backend.md | 28 + .../qiskit/0.46/qiskit.providers.BackendV1.md | 213 + .../qiskit/0.46/qiskit.providers.BackendV2.md | 382 ++ .../qiskit.providers.BackendV2Converter.md | 333 ++ docs/api/qiskit/0.46/qiskit.providers.Job.md | 28 + .../qiskit/0.46/qiskit.providers.JobStatus.md | 62 + .../api/qiskit/0.46/qiskit.providers.JobV1.md | 170 + .../qiskit/0.46/qiskit.providers.Options.md | 125 + .../qiskit/0.46/qiskit.providers.Provider.md | 28 + .../0.46/qiskit.providers.ProviderV1.md | 76 + .../0.46/qiskit.providers.QubitProperties.md | 42 + ....providers.basic_provider.BasicProvider.md | 76 + ...iders.basic_provider.BasicProviderError.md | 20 + ...oviders.basic_provider.BasicProviderJob.md | 184 + ...providers.basic_provider.BasicSimulator.md | 413 ++ ...qiskit.providers.basicaer.BasicAerError.md | 24 + .../qiskit.providers.basicaer.BasicAerJob.md | 180 + ...kit.providers.basicaer.BasicAerProvider.md | 80 + ...skit.providers.basicaer.QasmSimulatorPy.md | 243 + ...oviders.basicaer.StatevectorSimulatorPy.md | 243 + ...t.providers.basicaer.UnitarySimulatorPy.md | 252 ++ .../qiskit.providers.convert_to_target.md | 26 + ...s.fake_provider.ConfigurableFakeBackend.md | 164 + .../qiskit.providers.fake_provider.Fake1Q.md | 136 + ...kit.providers.fake_provider.FakeAlmaden.md | 175 + ...t.providers.fake_provider.FakeAlmadenV2.md | 361 ++ ...skit.providers.fake_provider.FakeArmonk.md | 183 + ...it.providers.fake_provider.FakeArmonkV2.md | 355 ++ ...skit.providers.fake_provider.FakeAthens.md | 179 + ...it.providers.fake_provider.FakeAthensV2.md | 351 ++ ...it.providers.fake_provider.FakeAuckland.md | 351 ++ ...providers.fake_provider.FakeBackend5QV2.md | 331 ++ ...t.providers.fake_provider.FakeBackendV2.md | 331 ++ ...iskit.providers.fake_provider.FakeBelem.md | 179 + ...kit.providers.fake_provider.FakeBelemV2.md | 351 ++ ....providers.fake_provider.FakeBoeblingen.md | 189 + ...roviders.fake_provider.FakeBoeblingenV2.md | 361 ++ ...skit.providers.fake_provider.FakeBogota.md | 179 + ...it.providers.fake_provider.FakeBogotaV2.md | 351 ++ ...it.providers.fake_provider.FakeBrooklyn.md | 179 + ....providers.fake_provider.FakeBrooklynV2.md | 351 ++ ....providers.fake_provider.FakeBurlington.md | 171 + ...roviders.fake_provider.FakeBurlingtonV2.md | 357 ++ ...iskit.providers.fake_provider.FakeCairo.md | 179 + ...kit.providers.fake_provider.FakeCairoV2.md | 351 ++ ...t.providers.fake_provider.FakeCambridge.md | 177 + ...providers.fake_provider.FakeCambridgeV2.md | 363 ++ ....providers.fake_provider.FakeCasablanca.md | 179 + ...roviders.fake_provider.FakeCasablancaV2.md | 351 ++ ...iskit.providers.fake_provider.FakeEssex.md | 173 + ...kit.providers.fake_provider.FakeEssexV2.md | 359 ++ ...skit.providers.fake_provider.FakeGeneva.md | 351 ++ ...t.providers.fake_provider.FakeGuadalupe.md | 179 + ...providers.fake_provider.FakeGuadalupeV2.md | 351 ++ ...iskit.providers.fake_provider.FakeHanoi.md | 179 + ...kit.providers.fake_provider.FakeHanoiV2.md | 351 ++ ...kit.providers.fake_provider.FakeJakarta.md | 179 + ...t.providers.fake_provider.FakeJakartaV2.md | 351 ++ ...roviders.fake_provider.FakeJohannesburg.md | 175 + ...viders.fake_provider.FakeJohannesburgV2.md | 361 ++ ...kit.providers.fake_provider.FakeKolkata.md | 179 + ...t.providers.fake_provider.FakeKolkataV2.md | 351 ++ ...iskit.providers.fake_provider.FakeLagos.md | 179 + ...kit.providers.fake_provider.FakeLagosV2.md | 351 ++ ...qiskit.providers.fake_provider.FakeLima.md | 179 + ...skit.providers.fake_provider.FakeLimaV2.md | 351 ++ ...skit.providers.fake_provider.FakeLondon.md | 173 + ...it.providers.fake_provider.FakeLondonV2.md | 359 ++ ...t.providers.fake_provider.FakeManhattan.md | 179 + ...providers.fake_provider.FakeManhattanV2.md | 351 ++ ...skit.providers.fake_provider.FakeManila.md | 179 + ...it.providers.fake_provider.FakeManilaV2.md | 351 ++ ...t.providers.fake_provider.FakeMelbourne.md | 140 + ...providers.fake_provider.FakeMelbourneV2.md | 351 ++ ...it.providers.fake_provider.FakeMontreal.md | 179 + ....providers.fake_provider.FakeMontrealV2.md | 351 ++ ...skit.providers.fake_provider.FakeMumbai.md | 179 + ...rs.fake_provider.FakeMumbaiFractionalCX.md | 327 ++ ...it.providers.fake_provider.FakeMumbaiV2.md | 351 ++ ...kit.providers.fake_provider.FakeNairobi.md | 179 + ...t.providers.fake_provider.FakeNairobiV2.md | 351 ++ ...providers.fake_provider.FakeOpenPulse2Q.md | 149 + ...providers.fake_provider.FakeOpenPulse3Q.md | 147 + ...qiskit.providers.fake_provider.FakeOslo.md | 351 ++ ...kit.providers.fake_provider.FakeOurense.md | 171 + ...t.providers.fake_provider.FakeOurenseV2.md | 357 ++ ...iskit.providers.fake_provider.FakeParis.md | 191 + ...kit.providers.fake_provider.FakeParisV2.md | 363 ++ ...iskit.providers.fake_provider.FakePerth.md | 351 ++ ...roviders.fake_provider.FakePoughkeepsie.md | 144 + ...viders.fake_provider.FakePoughkeepsieV2.md | 351 ++ ...skit.providers.fake_provider.FakePrague.md | 351 ++ ...it.providers.fake_provider.FakeProvider.md | 82 + ....fake_provider.FakeProviderForBackendV2.md | 82 + ...oviders.fake_provider.FakeQasmSimulator.md | 138 + ...iskit.providers.fake_provider.FakeQuito.md | 179 + ...kit.providers.fake_provider.FakeQuitoV2.md | 351 ++ ...t.providers.fake_provider.FakeRochester.md | 165 + ...providers.fake_provider.FakeRochesterV2.md | 351 ++ ...qiskit.providers.fake_provider.FakeRome.md | 179 + ...skit.providers.fake_provider.FakeRomeV2.md | 351 ++ ...providers.fake_provider.FakeRueschlikon.md | 140 + ...it.providers.fake_provider.FakeSantiago.md | 179 + ....providers.fake_provider.FakeSantiagoV2.md | 351 ++ ....providers.fake_provider.FakeSherbrooke.md | 351 ++ ...t.providers.fake_provider.FakeSingapore.md | 175 + ...providers.fake_provider.FakeSingaporeV2.md | 361 ++ ...skit.providers.fake_provider.FakeSydney.md | 179 + ...it.providers.fake_provider.FakeSydneyV2.md | 351 ++ ...it.providers.fake_provider.FakeTenerife.md | 142 + ...iskit.providers.fake_provider.FakeTokyo.md | 144 + ...kit.providers.fake_provider.FakeToronto.md | 179 + ...t.providers.fake_provider.FakeTorontoV2.md | 351 ++ ...it.providers.fake_provider.FakeValencia.md | 179 + ....providers.fake_provider.FakeValenciaV2.md | 351 ++ ...qiskit.providers.fake_provider.FakeVigo.md | 171 + ...skit.providers.fake_provider.FakeVigoV2.md | 357 ++ ....providers.fake_provider.FakeWashington.md | 179 + ...roviders.fake_provider.FakeWashingtonV2.md | 351 ++ ...it.providers.fake_provider.FakeYorktown.md | 173 + ....providers.fake_provider.FakeYorktownV2.md | 359 ++ ...roviders.fake_provider.GenericBackendV2.md | 354 ++ ...t.providers.models.BackendConfiguration.md | 138 + ...skit.providers.models.BackendProperties.md | 320 ++ .../qiskit.providers.models.BackendStatus.md | 70 + .../0.46/qiskit.providers.models.Command.md | 71 + .../qiskit.providers.models.GateConfig.md | 86 + .../qiskit.providers.models.GateProperties.md | 83 + .../0.46/qiskit.providers.models.JobStatus.md | 86 + .../0.46/qiskit.providers.models.Nduv.md | 89 + ...viders.models.PulseBackendConfiguration.md | 284 ++ .../qiskit.providers.models.PulseDefaults.md | 64 + ...oviders.models.QasmBackendConfiguration.md | 204 + .../qiskit.providers.models.UchannelLO.md | 79 + .../qiskit.pulse.InstructionScheduleMap.md | 241 + docs/api/qiskit/0.46/qiskit.pulse.Schedule.md | 498 +++ .../qiskit/0.46/qiskit.pulse.ScheduleBlock.md | 662 +++ .../qiskit.pulse.channels.AcquireChannel.md | 68 + .../qiskit.pulse.channels.ControlChannel.md | 68 + .../qiskit.pulse.channels.DriveChannel.md | 68 + .../qiskit.pulse.channels.MeasureChannel.md | 68 + .../0.46/qiskit.pulse.channels.MemorySlot.md | 68 + .../qiskit.pulse.channels.RegisterSlot.md | 68 + .../qiskit.pulse.channels.SnapshotChannel.md | 64 + .../0.46/qiskit.pulse.instructions.Acquire.md | 289 ++ .../0.46/qiskit.pulse.instructions.Call.md | 303 ++ .../0.46/qiskit.pulse.instructions.Delay.md | 263 ++ .../0.46/qiskit.pulse.instructions.Play.md | 257 ++ .../qiskit.pulse.instructions.Reference.md | 268 ++ ...skit.pulse.instructions.RelativeBarrier.md | 244 + .../qiskit.pulse.instructions.SetFrequency.md | 265 ++ .../qiskit.pulse.instructions.SetPhase.md | 263 ++ ...iskit.pulse.instructions.ShiftFrequency.md | 255 ++ .../qiskit.pulse.instructions.ShiftPhase.md | 267 ++ .../qiskit.pulse.instructions.Snapshot.md | 261 ++ .../qiskit.pulse.instructions.TimeBlockade.md | 280 ++ ...qiskit.pulse.library.Constant_class.rst.md | 45 + .../qiskit.pulse.library.Cos_class.rst.md | 44 + .../qiskit.pulse.library.Drag_class.rst.md | 61 + .../qiskit.pulse.library.GaussianDeriv.md | 44 + .../qiskit.pulse.library.GaussianSquare.md | 79 + ...qiskit.pulse.library.GaussianSquareDrag.md | 90 + ...qiskit.pulse.library.Gaussian_class.rst.md | 50 + .../qiskit.pulse.library.ParametricPulse.md | 138 + ...qiskit.pulse.library.Sawtooth_class.rst.md | 45 + .../0.46/qiskit.pulse.library.SechDeriv.md | 44 + .../0.46/qiskit.pulse.library.Sech_fun.rst.md | 53 + .../qiskit.pulse.library.Sin_class.rst.md | 44 + .../qiskit.pulse.library.Square_fun.rst.md | 45 + .../qiskit.pulse.library.SymbolicPulse.md | 258 ++ ...qiskit.pulse.library.Triangle_class.rst.md | 44 + .../0.46/qiskit.pulse.library.Waveform.md | 113 + ...skit.pulse.library.gaussian_square_echo.md | 77 + ...qiskit.pulse.transforms.AlignEquispaced.md | 62 + .../0.46/qiskit.pulse.transforms.AlignFunc.md | 82 + .../0.46/qiskit.pulse.transforms.AlignLeft.md | 52 + .../qiskit.pulse.transforms.AlignRight.md | 52 + ...qiskit.pulse.transforms.AlignSequential.md | 52 + .../0.46/qiskit.qobj.GateCalibration.md | 65 + .../0.46/qiskit.qobj.PulseLibraryItem.md | 63 + docs/api/qiskit/0.46/qiskit.qobj.PulseQobj.md | 84 + .../0.46/qiskit.qobj.PulseQobjConfig.md | 73 + .../0.46/qiskit.qobj.PulseQobjExperiment.md | 66 + .../qiskit.qobj.PulseQobjExperimentConfig.md | 64 + .../0.46/qiskit.qobj.PulseQobjInstruction.md | 78 + .../qiskit.qobj.QasmExperimentCalibrations.md | 62 + docs/api/qiskit/0.46/qiskit.qobj.QasmQobj.md | 84 + .../qiskit/0.46/qiskit.qobj.QasmQobjConfig.md | 75 + .../0.46/qiskit.qobj.QasmQobjExperiment.md | 66 + .../qiskit.qobj.QasmQobjExperimentConfig.md | 63 + .../0.46/qiskit.qobj.QasmQobjInstruction.md | 73 + .../0.46/qiskit.qobj.QobjExperimentHeader.md | 62 + .../api/qiskit/0.46/qiskit.qobj.QobjHeader.md | 62 + .../0.46/qiskit.qobj.QobjMeasurementOption.md | 63 + .../0.46/qiskit.quantum_info.CNOTDihedral.md | 361 ++ .../qiskit/0.46/qiskit.quantum_info.Chi.md | 395 ++ .../qiskit/0.46/qiskit.quantum_info.Choi.md | 407 ++ .../0.46/qiskit.quantum_info.Clifford.md | 661 +++ .../0.46/qiskit.quantum_info.DensityMatrix.md | 703 +++ .../qiskit/0.46/qiskit.quantum_info.Kraus.md | 395 ++ .../0.46/qiskit.quantum_info.Operator.md | 488 ++ .../qiskit/0.46/qiskit.quantum_info.PTM.md | 403 ++ .../qiskit/0.46/qiskit.quantum_info.Pauli.md | 589 +++ .../0.46/qiskit.quantum_info.PauliList.md | 865 ++++ .../0.46/qiskit.quantum_info.Quaternion.md | 126 + .../0.46/qiskit.quantum_info.ScalarOp.md | 302 ++ .../0.46/qiskit.quantum_info.SparsePauliOp.md | 881 ++++ .../qiskit.quantum_info.StabilizerState.md | 438 ++ .../0.46/qiskit.quantum_info.Statevector.md | 732 +++ .../0.46/qiskit.quantum_info.Stinespring.md | 399 ++ .../0.46/qiskit.quantum_info.SuperOp.md | 395 ++ .../0.46/qiskit.quantum_info.Z2Symmetries.md | 192 + .../0.46/qiskit.quantum_info.pauli_basis.md | 31 + .../qiskit.result.BaseReadoutMitigator.md | 69 + ...iskit.result.CorrelatedReadoutMitigator.md | 166 + docs/api/qiskit/0.46/qiskit.result.Counts.md | 204 + .../qiskit.result.LocalReadoutMitigator.md | 172 + .../0.46/qiskit.result.ProbDistribution.md | 161 + .../0.46/qiskit.result.QuasiDistribution.md | 199 + docs/api/qiskit/0.46/qiskit.result.Result.md | 258 ++ .../qiskit/0.46/qiskit.result.ResultError.md | 34 + .../qiskit.synthesis.EvolutionSynthesis.md | 56 + .../0.46/qiskit.synthesis.LieTrotter.md | 79 + .../qiskit.synthesis.MatrixExponential.md | 58 + ...iskit.synthesis.OneQubitEulerDecomposer.md | 106 + .../0.46/qiskit.synthesis.ProductFormula.md | 66 + .../qiskit/0.46/qiskit.synthesis.QDrift.md | 68 + ...it.synthesis.SolovayKitaevDecomposition.md | 93 + .../0.46/qiskit.synthesis.SuzukiTrotter.md | 86 + ...iskit.synthesis.TwoQubitBasisDecomposer.md | 89 + .../0.46/qiskit.synthesis.XXDecomposer.md | 41 + .../0.46/qiskit.synthesis.unitary.aqc.AQC.md | 49 + ...ynthesis.unitary.aqc.ApproximateCircuit.md | 240 + ...esis.unitary.aqc.ApproximatingObjective.md | 74 + ...t.synthesis.unitary.aqc.CNOTUnitCircuit.md | 242 + ...synthesis.unitary.aqc.CNOTUnitObjective.md | 43 + ...is.unitary.aqc.DefaultCNOTUnitObjective.md | 85 + ...hesis.unitary.aqc.FastCNOTUnitObjective.md | 69 + .../0.46/qiskit.transpiler.AnalysisPass.md | 109 + .../0.46/qiskit.transpiler.CouplingMap.md | 426 ++ .../qiskit.transpiler.FencedDAGCircuit.md | 22 + .../qiskit.transpiler.FencedPropertySet.md | 22 + .../qiskit.transpiler.InstructionDurations.md | 116 + ...qiskit.transpiler.InstructionProperties.md | 52 + .../qiskit/0.46/qiskit.transpiler.Layout.md | 267 ++ .../0.46/qiskit.transpiler.PassManager.md | 217 + .../qiskit.transpiler.PassManagerConfig.md | 70 + .../qiskit.transpiler.StagedPassManager.md | 241 + .../qiskit/0.46/qiskit.transpiler.Target.md | 649 +++ .../qiskit.transpiler.TransformationPass.md | 109 + .../0.46/qiskit.transpiler.TranspileLayout.md | 234 + .../qiskit.transpiler.passes.ALAPSchedule.md | 130 + ....transpiler.passes.ALAPScheduleAnalysis.md | 133 + ...it.transpiler.passes.AQCSynthesisPlugin.md | 181 + .../qiskit.transpiler.passes.ASAPSchedule.md | 134 + ....transpiler.passes.ASAPScheduleAnalysis.md | 133 + .../qiskit.transpiler.passes.AlignMeasures.md | 165 + .../qiskit.transpiler.passes.ApplyLayout.md | 121 + ...r.passes.BarrierBeforeFinalMeasurements.md | 103 + .../qiskit.transpiler.passes.BasicSwap.md | 127 + ...iskit.transpiler.passes.BasisTranslator.md | 172 + .../qiskit.transpiler.passes.CSPLayout.md | 118 + ...qiskit.transpiler.passes.CXCancellation.md | 113 + ...it.transpiler.passes.CheckGateDirection.md | 114 + .../0.46/qiskit.transpiler.passes.CheckMap.md | 116 + .../qiskit.transpiler.passes.Collect1qRuns.md | 105 + ...iskit.transpiler.passes.Collect2qBlocks.md | 105 + ...skit.transpiler.passes.CollectCliffords.md | 119 + ...ranspiler.passes.CollectLinearFunctions.md | 119 + ...t.transpiler.passes.CollectMultiQBlocks.md | 133 + ...t.transpiler.passes.CommutationAnalysis.md | 105 + ...anspiler.passes.CommutativeCancellation.md | 130 + ...r.passes.CommutativeInverseCancellation.md | 113 + ...transpiler.passes.Commuting2qGateRouter.md | 206 + ...kit.transpiler.passes.ConsolidateBlocks.md | 121 + ...transpiler.passes.ConstrainedReschedule.md | 175 + ...t.transpiler.passes.ContainsInstruction.md | 110 + ...nspiler.passes.ConvertConditionsToIfOps.md | 111 + .../0.46/qiskit.transpiler.passes.CountOps.md | 103 + ...t.transpiler.passes.CountOpsLongestPath.md | 103 + ...spiler.passes.CrosstalkAdaptiveSchedule.md | 343 ++ .../qiskit.transpiler.passes.DAGFixedPoint.md | 103 + ...qiskit.transpiler.passes.DAGLongestPath.md | 101 + .../qiskit.transpiler.passes.Decompose.md | 119 + .../qiskit.transpiler.passes.DenseLayout.md | 125 + .../0.46/qiskit.transpiler.passes.Depth.md | 105 + ...t.transpiler.passes.DynamicalDecoupling.md | 202 + ...nspiler.passes.EchoRZXWeylDecomposition.md | 128 + ...it.transpiler.passes.EnlargeWithAncilla.md | 119 + .../qiskit.transpiler.passes.FixedPoint.md | 109 + ...transpiler.passes.FullAncillaAllocation.md | 141 + .../qiskit.transpiler.passes.GateDirection.md | 153 + .../qiskit.transpiler.passes.GatesInBasis.md | 108 + ...it.transpiler.passes.HighLevelSynthesis.md | 152 + ...qiskit.transpiler.passes.HoareOptimizer.md | 119 + ...nspiler.passes.InstructionDurationCheck.md | 118 + ...t.transpiler.passes.InverseCancellation.md | 123 + ...skit.transpiler.passes.Layout2qDistance.md | 110 + ...nspiler.passes.LinearFunctionsSynthesis.md | 124 + ...er.passes.LinearFunctionsToPermutations.md | 109 + .../qiskit.transpiler.passes.LookaheadSwap.md | 145 + ...transpiler.passes.MergeAdjacentBarriers.md | 138 + .../qiskit.transpiler.passes.MinimumPoint.md | 121 + ...t.transpiler.passes.NoiseAdaptiveLayout.md | 156 + ...skit.transpiler.passes.NormalizeRXAngle.md | 156 + ...skit.transpiler.passes.NumTensorFactors.md | 103 + ...iskit.transpiler.passes.Optimize1qGates.md | 158 + ...ler.passes.Optimize1qGatesDecomposition.md | 129 + ...passes.Optimize1qGatesSimpleCommutation.md | 123 + ...kit.transpiler.passes.OptimizeCliffords.md | 113 + .../0.46/qiskit.transpiler.passes.PadDelay.md | 149 + ...ranspiler.passes.PadDynamicalDecoupling.md | 207 + .../qiskit.transpiler.passes.PulseGates.md | 178 + ....transpiler.passes.RXCalibrationBuilder.md | 187 + ...transpiler.passes.RZXCalibrationBuilder.md | 199 + ...iler.passes.RZXCalibrationBuilderNoEcho.md | 201 + ...qiskit.transpiler.passes.RemoveBarriers.md | 124 + ...passes.RemoveDiagonalGatesBeforeMeasure.md | 115 + ...anspiler.passes.RemoveFinalMeasurements.md | 117 + ...ranspiler.passes.RemoveResetInZeroState.md | 113 + ....passes.ResetAfterMeasureSimplification.md | 103 + .../qiskit.transpiler.passes.SabreLayout.md | 213 + ...qiskit.transpiler.passes.SabrePreLayout.md | 171 + .../qiskit.transpiler.passes.SabreSwap.md | 178 + .../qiskit.transpiler.passes.SetIOLatency.md | 116 + .../qiskit.transpiler.passes.SetLayout.md | 126 + .../0.46/qiskit.transpiler.passes.Size.md | 107 + .../qiskit.transpiler.passes.SolovayKitaev.md | 206 + ...ranspiler.passes.SolovayKitaevSynthesis.md | 173 + ...qiskit.transpiler.passes.StochasticSwap.md | 139 + ....transpiler.passes.TemplateOptimization.md | 122 + ...it.transpiler.passes.TimeUnitConversion.md | 132 + ...iler.passes.TranslateParameterizedGates.md | 174 + .../qiskit.transpiler.passes.TrivialLayout.md | 125 + ...skit.transpiler.passes.UnitarySynthesis.md | 135 + ...qiskit.transpiler.passes.Unroll3qOrMore.md | 124 + ...anspiler.passes.UnrollCustomDefinitions.md | 136 + ...qiskit.transpiler.passes.UnrollForLoops.md | 123 + .../0.46/qiskit.transpiler.passes.Unroller.md | 131 + .../qiskit.transpiler.passes.VF2Layout.md | 137 + .../qiskit.transpiler.passes.VF2PostLayout.md | 139 + ...it.transpiler.passes.ValidatePulseGates.md | 132 + .../0.46/qiskit.transpiler.passes.Width.md | 103 + ...nthesis.plugin.HighLevelSynthesisPlugin.md | 48 + ....plugin.HighLevelSynthesisPluginManager.md | 36 + ...synthesis.plugin.UnitarySynthesisPlugin.md | 200 + ...is.plugin.UnitarySynthesisPluginManager.md | 20 + ...s.plugin.unitary_synthesis_plugin_names.md | 26 + ...smanagers.plugin.PassManagerStagePlugin.md | 39 + ...rs.plugin.PassManagerStagePluginManager.md | 32 + .../0.46/qiskit.utils.QuantumInstance.md | 316 ++ ...kit.utils.mitigation.CompleteMeasFitter.md | 128 + ...kit.utils.mitigation.TensoredMeasFitter.md | 139 + .../qiskit.visualization.array_to_latex.md | 51 + ...ualization.circuit.qcstyle.DefaultStyle.md | 161 + .../qiskit.visualization.circuit_drawer.md | 91 + .../0.46/qiskit.visualization.dag_drawer.md | 62 + ...iskit.visualization.pass_manager_drawer.md | 62 + ...it.visualization.plot_bloch_multivector.md | 85 + .../qiskit.visualization.plot_bloch_vector.md | 62 + ...iskit.visualization.plot_circuit_layout.md | 62 + .../qiskit.visualization.plot_coupling_map.md | 62 + .../qiskit.visualization.plot_distribution.md | 79 + .../qiskit.visualization.plot_error_map.md | 51 + .../qiskit.visualization.plot_gate_map.md | 62 + .../qiskit.visualization.plot_histogram.md | 84 + .../qiskit.visualization.plot_state_city.md | 89 + .../qiskit.visualization.plot_state_hinton.md | 62 + ...iskit.visualization.plot_state_paulivec.md | 92 + ...qiskit.visualization.plot_state_qsphere.md | 81 + ...qiskit.visualization.pulse.IQXDebugging.md | 113 + .../qiskit.visualization.pulse.IQXSimple.md | 110 + .../qiskit.visualization.pulse.IQXStandard.md | 110 + .../0.46/qiskit.visualization.pulse_drawer.md | 323 ++ .../qiskit.visualization.timeline_drawer.md | 321 ++ ...skit.visualization.visualize_transition.md | 39 + docs/api/qiskit/0.46/qobj.md | 51 + docs/api/qiskit/0.46/qpy.md | 1088 +++++ docs/api/qiskit/0.46/quantum_info.md | 944 ++++ docs/api/qiskit/0.46/result.md | 160 + docs/api/qiskit/0.46/scheduler.md | 122 + docs/api/qiskit/0.46/synthesis.md | 729 +++ docs/api/qiskit/0.46/synthesis_aqc.md | 168 + docs/api/qiskit/0.46/tools.md | 140 + docs/api/qiskit/0.46/tools_jupyter.md | 86 + docs/api/qiskit/0.46/transpiler.md | 980 ++++ .../qiskit/0.46/transpiler_builtin_plugins.md | 8 + docs/api/qiskit/0.46/transpiler_passes.md | 162 + docs/api/qiskit/0.46/transpiler_plugins.md | 170 + docs/api/qiskit/0.46/transpiler_preset.md | 398 ++ .../0.46/transpiler_synthesis_plugins.md | 169 + docs/api/qiskit/0.46/utils.md | 712 +++ docs/api/qiskit/0.46/utils_mitigation.md | 37 + docs/api/qiskit/0.46/visualization.md | 245 + public/images/api/qiskit/0.46/circuit-1.png | Bin 0 -> 4978 bytes public/images/api/qiskit/0.46/circuit-2.png | Bin 0 -> 3885 bytes public/images/api/qiskit/0.46/circuit-3.png | Bin 0 -> 5628 bytes public/images/api/qiskit/0.46/circuit-4.png | Bin 0 -> 27444 bytes public/images/api/qiskit/0.46/circuit-5.png | Bin 0 -> 7137 bytes .../api/qiskit/0.46/circuit_library-1.png | Bin 0 -> 5904 bytes .../images/api/qiskit/0.46/converters-1.png | Bin 0 -> 8110 bytes public/images/api/qiskit/0.46/depth.gif | Bin 0 -> 2874095 bytes public/images/api/qiskit/0.46/mapping.png | Bin 0 -> 60165 bytes .../0.46/providers_fake_provider-1_00.png | Bin 0 -> 12644 bytes .../0.46/providers_fake_provider-1_01.png | Bin 0 -> 21668 bytes .../0.46/providers_fake_provider-1_02.png | Bin 0 -> 14483 bytes public/images/api/qiskit/0.46/pulse-1.png | Bin 0 -> 15975 bytes public/images/api/qiskit/0.46/pulse-2.png | Bin 0 -> 16712 bytes public/images/api/qiskit/0.46/pulse-3.png | Bin 0 -> 31312 bytes public/images/api/qiskit/0.46/pulse-4.png | Bin 0 -> 11069 bytes public/images/api/qiskit/0.46/pulse-5.png | Bin 0 -> 54614 bytes public/images/api/qiskit/0.46/pulse-6.png | Bin 0 -> 19242 bytes public/images/api/qiskit/0.46/pulse-7.png | Bin 0 -> 16404 bytes public/images/api/qiskit/0.46/pulse-8.png | Bin 0 -> 11645 bytes public/images/api/qiskit/0.46/pulse-9.png | Bin 0 -> 14096 bytes public/images/api/qiskit/0.46/qasm3-1.png | Bin 0 -> 25454 bytes .../0.46/qiskit-circuit-ControlledGate-1.png | Bin 0 -> 4422 bytes .../0.46/qiskit-circuit-ControlledGate-2.png | Bin 0 -> 6965 bytes .../0.46/qiskit-circuit-InstructionSet-1.png | Bin 0 -> 8858 bytes .../0.46/qiskit-circuit-Operation-1.png | Bin 0 -> 5552 bytes .../0.46/qiskit-circuit-Parameter-1_00.png | Bin 0 -> 1697 bytes .../0.46/qiskit-circuit-Parameter-1_01.png | Bin 0 -> 5365 bytes .../0.46/qiskit-circuit-QuantumCircuit-1.png | Bin 0 -> 6702 bytes .../0.46/qiskit-circuit-QuantumCircuit-2.png | Bin 0 -> 15875 bytes .../qiskit-circuit-QuantumCircuit-3_00.png | Bin 0 -> 3595 bytes .../qiskit-circuit-QuantumCircuit-3_01.png | Bin 0 -> 3580 bytes .../qiskit-circuit-QuantumCircuit-4_00.png | Bin 0 -> 3527 bytes .../qiskit-circuit-QuantumCircuit-4_01.png | Bin 0 -> 3850 bytes .../0.46/qiskit-circuit-QuantumCircuit-5.png | Bin 0 -> 3673 bytes .../0.46/qiskit-circuit-QuantumCircuit-6.png | Bin 0 -> 4169 bytes .../0.46/qiskit-circuit-library-AND-1.png | Bin 0 -> 16847 bytes .../0.46/qiskit-circuit-library-AND-2.png | Bin 0 -> 17434 bytes ...skit-circuit-library-FourierChecking-1.png | Bin 0 -> 11424 bytes .../0.46/qiskit-circuit-library-GMS-1.png | Bin 0 -> 12635 bytes .../0.46/qiskit-circuit-library-GR-1.png | Bin 0 -> 18949 bytes .../0.46/qiskit-circuit-library-GRX-1.png | Bin 0 -> 18704 bytes .../0.46/qiskit-circuit-library-GRY-1.png | Bin 0 -> 18949 bytes .../0.46/qiskit-circuit-library-GRZ-1.png | Bin 0 -> 12178 bytes .../qiskit-circuit-library-GraphState-1.png | Bin 0 -> 15618 bytes ...circuit-library-HiddenLinearFunction-1.png | Bin 0 -> 12956 bytes .../0.46/qiskit-circuit-library-IQP-1.png | Bin 0 -> 6586 bytes .../0.46/qiskit-circuit-library-IQP-2.png | Bin 0 -> 14797 bytes .../qiskit-circuit-library-InnerProduct-1.png | Bin 0 -> 14228 bytes .../qiskit-circuit-library-MCMTVChain-1.png | Bin 0 -> 13705 bytes .../0.46/qiskit-circuit-library-OR-1.png | Bin 0 -> 20190 bytes .../0.46/qiskit-circuit-library-OR-2.png | Bin 0 -> 18418 bytes ...iskit-circuit-library-PauliTwoDesign-1.png | Bin 0 -> 10634 bytes .../qiskit-circuit-library-Permutation-1.png | Bin 0 -> 9125 bytes .../qiskit-circuit-library-Permutation-2.png | Bin 0 -> 15619 bytes ...skit-circuit-library-PermutationGate-1.png | Bin 0 -> 7652 bytes ...skit-circuit-library-PermutationGate-2.png | Bin 0 -> 15209 bytes ...skit-circuit-library-PhaseEstimation-1.png | Bin 0 -> 12047 bytes ...t-circuit-library-PiecewiseChebyshev-1.png | Bin 0 -> 7651 bytes .../0.46/qiskit-circuit-library-QFT-1.png | Bin 0 -> 11619 bytes .../0.46/qiskit-circuit-library-QFT-2.png | Bin 0 -> 11789 bytes .../0.46/qiskit-circuit-library-QFT-3.png | Bin 0 -> 11890 bytes ...qiskit-circuit-library-QuantumVolume-1.png | Bin 0 -> 9480 bytes ...qiskit-circuit-library-QuantumVolume-2.png | Bin 0 -> 18170 bytes .../0.46/qiskit-circuit-library-XOR-1.png | Bin 0 -> 12576 bytes .../qiskit-pulse-library-SymbolicPulse-1.png | Bin 0 -> 11401 bytes .../qiskit-quantum_info-Statevector-1.png | Bin 0 -> 7558 bytes ...spiler-passes-DynamicalDecoupling-1_00.png | Bin 0 -> 22803 bytes ...spiler-passes-DynamicalDecoupling-1_01.png | Bin 0 -> 23583 bytes ...ler-passes-PadDynamicalDecoupling-1_00.png | Bin 0 -> 22803 bytes ...ler-passes-PadDynamicalDecoupling-1_01.png | Bin 0 -> 23583 bytes ...kit-transpiler-passes-RemoveBarriers-1.png | Bin 0 -> 1561 bytes .../qiskit-visualization-circuit_drawer-1.png | Bin 0 -> 3934 bytes ...visualization-plot_bloch_multivector-1.png | Bin 0 -> 92847 bytes ...visualization-plot_bloch_multivector-2.png | Bin 0 -> 95603 bytes ...skit-visualization-plot_bloch_vector-1.png | Bin 0 -> 73448 bytes ...skit-visualization-plot_bloch_vector-2.png | Bin 0 -> 74554 bytes ...it-visualization-plot_circuit_layout-1.png | Bin 0 -> 8112 bytes ...skit-visualization-plot_coupling_map-1.png | Bin 0 -> 8007 bytes ...t-visualization-plot_distribution-1_00.png | Bin 0 -> 16020 bytes ...t-visualization-plot_distribution-1_01.png | Bin 0 -> 20219 bytes ...t-visualization-plot_distribution-1_02.png | Bin 0 -> 20276 bytes .../qiskit-visualization-plot_error_map-1.png | Bin 0 -> 37014 bytes .../qiskit-visualization-plot_gate_map-1.png | Bin 0 -> 7345 bytes ...skit-visualization-plot_histogram-1_00.png | Bin 0 -> 12434 bytes ...skit-visualization-plot_histogram-1_01.png | Bin 0 -> 16199 bytes ...skit-visualization-plot_histogram-1_02.png | Bin 0 -> 16249 bytes ...qiskit-visualization-plot_state_city-1.png | Bin 0 -> 117324 bytes ...qiskit-visualization-plot_state_city-2.png | Bin 0 -> 159875 bytes ...skit-visualization-plot_state_hinton-1.png | Bin 0 -> 11116 bytes ...it-visualization-plot_state_paulivec-1.png | Bin 0 -> 17337 bytes ...it-visualization-plot_state_paulivec-2.png | Bin 0 -> 18522 bytes ...kit-visualization-plot_state_qsphere-1.png | Bin 0 -> 33861 bytes ...kit-visualization-plot_state_qsphere-2.png | Bin 0 -> 38572 bytes .../qiskit-visualization-pulse_drawer-1.png | Bin 0 -> 63840 bytes .../qiskit-visualization-pulse_drawer-2.png | Bin 0 -> 29394 bytes .../qiskit-visualization-pulse_drawer-3.png | Bin 0 -> 79687 bytes ...qiskit-visualization-timeline_drawer-1.png | Bin 0 -> 29867 bytes ...qiskit-visualization-timeline_drawer-2.png | Bin 0 -> 7453 bytes ...qiskit-visualization-timeline_drawer-3.png | Bin 0 -> 69676 bytes .../images/api/qiskit/0.46/transpiler-10.png | Bin 0 -> 7906 bytes .../images/api/qiskit/0.46/transpiler-11.png | Bin 0 -> 32887 bytes .../images/api/qiskit/0.46/transpiler-12.png | Bin 0 -> 8856 bytes .../images/api/qiskit/0.46/transpiler-13.png | Bin 0 -> 32887 bytes .../images/api/qiskit/0.46/transpiler-14.png | Bin 0 -> 19570 bytes .../images/api/qiskit/0.46/transpiler-15.png | Bin 0 -> 8855 bytes .../images/api/qiskit/0.46/transpiler-16.png | Bin 0 -> 91600 bytes .../images/api/qiskit/0.46/transpiler-17.png | Bin 0 -> 35255 bytes .../images/api/qiskit/0.46/transpiler-4.png | Bin 0 -> 6224 bytes .../images/api/qiskit/0.46/transpiler-5.png | Bin 0 -> 19791 bytes .../images/api/qiskit/0.46/transpiler-6.png | Bin 0 -> 9344 bytes .../images/api/qiskit/0.46/transpiler-7.png | Bin 0 -> 11696 bytes .../images/api/qiskit/0.46/transpiler-8.png | Bin 0 -> 8194 bytes .../images/api/qiskit/0.46/transpiler-9.png | Bin 0 -> 8392 bytes .../qiskit/0.46/transpiling_core_steps.png | Bin 0 -> 246632 bytes .../api/qiskit/0.46/visualization-1.png | Bin 0 -> 10426 bytes .../api/qiskit/0.46/visualization-2.png | Bin 0 -> 17293 bytes .../api/qiskit/0.46/visualization-3.png | Bin 0 -> 10033 bytes .../api/qiskit/0.46/visualization-4.png | Bin 0 -> 108756 bytes .../api/qiskit/0.46/visualization-5.png | Bin 0 -> 113083 bytes .../api/qiskit/0.46/visualization-6.png | Bin 0 -> 113083 bytes 931 files changed, 158491 insertions(+) create mode 100644 docs/api/qiskit/0.46/_package.json create mode 100644 docs/api/qiskit/0.46/_toc.json create mode 100644 docs/api/qiskit/0.46/algorithms.md create mode 100644 docs/api/qiskit/0.46/assembler.md create mode 100644 docs/api/qiskit/0.46/circuit.md create mode 100644 docs/api/qiskit/0.46/circuit_classical.md create mode 100644 docs/api/qiskit/0.46/circuit_library.md create mode 100644 docs/api/qiskit/0.46/circuit_singleton.md create mode 100644 docs/api/qiskit/0.46/classicalfunction.md create mode 100644 docs/api/qiskit/0.46/compiler.md create mode 100644 docs/api/qiskit/0.46/converters.md create mode 100644 docs/api/qiskit/0.46/dagcircuit.md create mode 100644 docs/api/qiskit/0.46/exceptions.md create mode 100644 docs/api/qiskit/0.46/execute.md create mode 100644 docs/api/qiskit/0.46/extensions.md create mode 100644 docs/api/qiskit/0.46/index.md create mode 100644 docs/api/qiskit/0.46/opflow.md create mode 100644 docs/api/qiskit/0.46/passmanager.md create mode 100644 docs/api/qiskit/0.46/primitives.md create mode 100644 docs/api/qiskit/0.46/providers.md create mode 100644 docs/api/qiskit/0.46/providers_basic_provider.md create mode 100644 docs/api/qiskit/0.46/providers_basicaer.md create mode 100644 docs/api/qiskit/0.46/providers_fake_provider.md create mode 100644 docs/api/qiskit/0.46/providers_models.md create mode 100644 docs/api/qiskit/0.46/pulse.md create mode 100644 docs/api/qiskit/0.46/qasm.md create mode 100644 docs/api/qiskit/0.46/qasm2.md create mode 100644 docs/api/qiskit/0.46/qasm3.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AlgorithmJob.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AmplificationProblem.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeAmplifier.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimationResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimator.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimatorResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.Eigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.EigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.EstimationProblem.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.EvolutionProblem.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.EvolutionResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimationResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.Grover.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.GroverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimationResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryEvolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryTimeEvolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimationResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.IterativePhaseEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.NumPyEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.NumPyMinimumEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.PVQD.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.PVQDResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationScale.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.QAOA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.RealEvolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.RealTimeEvolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.SciPyImaginaryEvolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.SciPyRealEvolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionProblem.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.TrotterQRTE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.VQD.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.VQDResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.VQE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.VarQITE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.VarQRTE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.Eigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.EigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQD.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQDResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseEstimatorGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseQGT.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseSamplerGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.EstimatorGradientResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffEstimatorGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffSamplerGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombEstimatorGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombQGT.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombSamplerGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftEstimatorGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftSamplerGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFI.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFIResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.QGTResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseEstimatorGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseQGT.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSAEstimatorGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSASamplerGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.SamplerGradientResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.gradients.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.QAOA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQEResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ADAM.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AQGD.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AskData.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.BOBYQA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CG.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.COBYLA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CRS.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L_RAND.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ESCH.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GSLS.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescent.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescentState.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.IMFIL.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ISRES.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.L_BFGS_B.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Minimizer.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NELDER_MEAD.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NFT.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Optimizer.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerState.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerSupportLevel.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.POWELL.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.P_BFGS.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.QNSPSA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SLSQP.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SNOBFIT.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SPSA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SciPyOptimizer.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SteppableOptimizer.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TNC.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TellData.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.UMDA.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.LearningRate.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.BaseStateFidelity.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.ComputeUncompute.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.StateFidelityResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.VariationalPrinciple.md create mode 100644 docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.md create mode 100644 docs/api/qiskit/0.46/qiskit.assembler.RunConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.AncillaQubit.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.AncillaRegister.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.AnnotatedOperation.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Bit.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.BreakLoopOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.CircuitInstruction.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ClassicalRegister.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Clbit.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.CommutationChecker.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ContinueLoopOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ControlFlowOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ControlModifier.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ControlledGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Delay.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.EquivalenceLibrary.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ForLoopOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Gate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.IfElseOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Instruction.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.InstructionSet.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.InverseModifier.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Operation.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Parameter.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ParameterExpression.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.ParameterVector.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.PowerModifier.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.QuantumCircuit.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.QuantumRegister.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Qubit.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.Register.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.SwitchCaseOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.WhileLoopOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.BooleanExpression.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunction.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.AND.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Barrier.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.C3SXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.C3XGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.C4XGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CCXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CCZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CDKMRippleCarryAdder.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CHGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CPhaseGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CRXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CRYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CRZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CSGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CSXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CSdgGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CSwapGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CU1Gate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CU3Gate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CUGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.CZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.DCXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Diagonal.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.DiagonalGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.DraperQFTAdder.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.ECRGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.EfficientSU2.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.EvolvedOperatorAnsatz.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.ExactReciprocal.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.ExcitationPreserving.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.FourierChecking.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.FunctionalPauliRotations.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GMS.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GR.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GRX.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GRY.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GRZ.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GlobalPhaseGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GraphState.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.GroverOperator.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.HGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.HRSCumulativeMultiplier.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.HamiltonianGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.HiddenLinearFunction.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.IGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.IQP.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Initialize.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.InnerProduct.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.IntegerComparator.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Isometry.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.LinearAmplitudeFunction.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.LinearFunction.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.LinearPauliRotations.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCMT.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCMTVChain.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCPhaseGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCXGrayCode.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCXRecursive.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MCXVChain.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.MSGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Measure.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.NLocal.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.OR.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PauliEvolutionGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PauliFeatureMap.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PauliGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PauliTwoDesign.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Permutation.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PermutationGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PhaseEstimation.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PhaseGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PhaseOracle.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseChebyshev.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseLinearPauliRotations.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.PolynomialPauliRotations.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.QAOAAnsatz.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.QFT.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.QuadraticForm.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.QuantumVolume.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RC3XGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RCCXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RGQFTMultiplier.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RVGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RXXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RYYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RZXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RZZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.RealAmplitudes.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.Reset.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.SGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.SXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.SXdgGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.SdgGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.StatePreparation.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.SwapGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.TGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.TdgGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.TwoLocal.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.U1Gate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.U2Gate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.U3Gate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UCGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UCPauliRotGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UCRXGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UCRYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UCRZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryOverlap.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.VBERippleCarryAdder.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.WeightedAdder.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.XGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.XOR.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.XXMinusYYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.XXPlusYYGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.YGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.ZFeatureMap.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.ZGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.ZZFeatureMap.md create mode 100644 docs/api/qiskit/0.46/qiskit.circuit.library.iSwapGate.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGCircuit.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDepNode.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDependency.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGInNode.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGNode.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOpNode.md create mode 100644 docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOutNode.md create mode 100644 docs/api/qiskit/0.46/qiskit.extensions.SingleQubitUnitary.md create mode 100644 docs/api/qiskit/0.46/qiskit.extensions.Snapshot.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.OperatorBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.AbelianGrouper.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.CircuitSampler.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.ConverterBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.DictToCircuitSum.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.PauliBasisChange.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.TwoQubitReduction.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.converters.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionFactory.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolvedOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.MatrixEvolution.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.PauliTrotterEvolution.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.QDrift.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.Suzuki.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.Trotter.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationFactory.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.evolutions.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.AerPauliExpectation.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.CVaRExpectation.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationFactory.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.MatrixExpectation.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.PauliExpectation.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.expectations.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitQFI.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.DerivativeBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.Gradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.GradientBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.Hessian.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.HessianBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.NaturalGradient.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.QFI.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.QFIBase.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.gradients.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.list_ops.ComposedOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.list_ops.ListOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.list_ops.SummedOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.list_ops.TensoredOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.list_ops.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.CircuitOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.MatrixOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliSumOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PrimitiveOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.TaperedPauliSumOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.Z2Symmetries.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.CVaRMeasurement.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.CircuitStateFn.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.DictStateFn.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.OperatorStateFn.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.SparseVectorStateFn.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.StateFn.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.VectorStateFn.md create mode 100644 docs/api/qiskit/0.46/qiskit.opflow.state_fns.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.BaseController.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.BasePassManager.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.ConditionalController.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.DoWhileController.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.FlowController.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.FlowControllerLinear.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.GenericPass.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.PassManagerState.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.PropertySet.md create mode 100644 docs/api/qiskit/0.46/qiskit.passmanager.WorkflowStatus.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.BackendEstimator.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.BackendSampler.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.BaseEstimator.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.BaseSampler.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.Estimator.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.EstimatorResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.Sampler.md create mode 100644 docs/api/qiskit/0.46/qiskit.primitives.SamplerResult.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.Backend.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.BackendV1.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.BackendV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.BackendV2Converter.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.Job.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.JobStatus.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.JobV1.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.Options.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.Provider.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.ProviderV1.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.QubitProperties.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProvider.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderError.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderJob.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicSimulator.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerError.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerJob.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerProvider.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basicaer.QasmSimulatorPy.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basicaer.StatevectorSimulatorPy.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.basicaer.UnitarySimulatorPy.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.convert_to_target.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.ConfigurableFakeBackend.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.Fake1Q.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmaden.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmadenV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonk.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonkV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthens.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthensV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAuckland.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackend5QV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackendV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelem.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelemV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingen.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingenV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogota.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogotaV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklyn.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklynV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlington.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlingtonV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairo.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairoV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridge.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridgeV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablanca.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablancaV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssex.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssexV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGeneva.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupe.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupeV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoi.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoiV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakarta.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakartaV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburg.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburgV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkata.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkataV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagos.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagosV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLima.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLimaV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondon.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondonV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattan.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattanV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManila.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManilaV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourne.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourneV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontreal.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontrealV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbai.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiFractionalCX.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobi.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobiV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse2Q.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse3Q.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOslo.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurense.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurenseV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParis.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParisV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePerth.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsie.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsieV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePrague.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProvider.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProviderForBackendV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQasmSimulator.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuito.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuitoV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochester.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochesterV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRome.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRomeV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRueschlikon.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiago.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiagoV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSherbrooke.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingapore.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingaporeV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydney.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydneyV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTenerife.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTokyo.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeToronto.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTorontoV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValencia.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValenciaV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigo.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigoV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashington.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashingtonV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktown.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktownV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.fake_provider.GenericBackendV2.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.BackendConfiguration.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.BackendProperties.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.BackendStatus.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.Command.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.GateConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.GateProperties.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.JobStatus.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.Nduv.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.PulseBackendConfiguration.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.PulseDefaults.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.QasmBackendConfiguration.md create mode 100644 docs/api/qiskit/0.46/qiskit.providers.models.UchannelLO.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.InstructionScheduleMap.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.Schedule.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.ScheduleBlock.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.AcquireChannel.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.ControlChannel.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.DriveChannel.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.MeasureChannel.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.MemorySlot.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.RegisterSlot.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.channels.SnapshotChannel.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.Acquire.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.Call.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.Delay.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.Play.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.Reference.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.RelativeBarrier.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.SetFrequency.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.SetPhase.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftFrequency.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftPhase.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.Snapshot.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.instructions.TimeBlockade.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Constant_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Cos_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Drag_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.GaussianDeriv.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquare.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquareDrag.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Gaussian_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.ParametricPulse.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Sawtooth_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.SechDeriv.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Sech_fun.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Sin_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Square_fun.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.SymbolicPulse.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Triangle_class.rst.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.Waveform.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.library.gaussian_square_echo.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignEquispaced.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignFunc.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignLeft.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignRight.md create mode 100644 docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignSequential.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.GateCalibration.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.PulseLibraryItem.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.PulseQobj.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.PulseQobjConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperiment.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperimentConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.PulseQobjInstruction.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QasmExperimentCalibrations.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QasmQobj.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QasmQobjConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperiment.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperimentConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QasmQobjInstruction.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QobjExperimentHeader.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QobjHeader.md create mode 100644 docs/api/qiskit/0.46/qiskit.qobj.QobjMeasurementOption.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.CNOTDihedral.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Chi.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Choi.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Clifford.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.DensityMatrix.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Kraus.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Operator.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.PTM.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Pauli.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.PauliList.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Quaternion.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.ScalarOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.SparsePauliOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.StabilizerState.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Statevector.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Stinespring.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.SuperOp.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.Z2Symmetries.md create mode 100644 docs/api/qiskit/0.46/qiskit.quantum_info.pauli_basis.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.BaseReadoutMitigator.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.CorrelatedReadoutMitigator.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.Counts.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.LocalReadoutMitigator.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.ProbDistribution.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.QuasiDistribution.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.Result.md create mode 100644 docs/api/qiskit/0.46/qiskit.result.ResultError.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.EvolutionSynthesis.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.LieTrotter.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.MatrixExponential.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.OneQubitEulerDecomposer.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.ProductFormula.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.QDrift.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.SolovayKitaevDecomposition.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.SuzukiTrotter.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.TwoQubitBasisDecomposer.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.XXDecomposer.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.AQC.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md create mode 100644 docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.AnalysisPass.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.CouplingMap.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.FencedDAGCircuit.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.FencedPropertySet.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.InstructionDurations.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.InstructionProperties.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.Layout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.PassManager.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.PassManagerConfig.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.StagedPassManager.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.Target.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.TransformationPass.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.TranspileLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPSchedule.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPScheduleAnalysis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.AQCSynthesisPlugin.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPSchedule.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPScheduleAnalysis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.AlignMeasures.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ApplyLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.BasicSwap.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.BasisTranslator.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CSPLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CXCancellation.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckGateDirection.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckMap.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect1qRuns.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect2qBlocks.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectCliffords.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectLinearFunctions.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectMultiQBlocks.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutationAnalysis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeCancellation.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeInverseCancellation.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Commuting2qGateRouter.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ConsolidateBlocks.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ConstrainedReschedule.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ContainsInstruction.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ConvertConditionsToIfOps.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOps.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOpsLongestPath.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.CrosstalkAdaptiveSchedule.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGFixedPoint.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGLongestPath.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Decompose.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.DenseLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Depth.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.DynamicalDecoupling.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.EnlargeWithAncilla.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.FixedPoint.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.FullAncillaAllocation.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.GateDirection.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.GatesInBasis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.HighLevelSynthesis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.HoareOptimizer.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.InstructionDurationCheck.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.InverseCancellation.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Layout2qDistance.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsSynthesis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsToPermutations.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.LookaheadSwap.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.MergeAdjacentBarriers.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.MinimumPoint.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.NoiseAdaptiveLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.NormalizeRXAngle.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.NumTensorFactors.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGates.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.OptimizeCliffords.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDelay.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDynamicalDecoupling.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.PulseGates.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RXCalibrationBuilder.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilder.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveBarriers.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveFinalMeasurements.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveResetInZeroState.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SabrePreLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreSwap.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SetIOLatency.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SetLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Size.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaev.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaevSynthesis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.StochasticSwap.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.TemplateOptimization.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.TimeUnitConversion.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.TranslateParameterizedGates.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.TrivialLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.UnitarySynthesis.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroll3qOrMore.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollCustomDefinitions.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollForLoops.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroller.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2Layout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2PostLayout.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.ValidatePulseGates.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.Width.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md create mode 100644 docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md create mode 100644 docs/api/qiskit/0.46/qiskit.utils.QuantumInstance.md create mode 100644 docs/api/qiskit/0.46/qiskit.utils.mitigation.CompleteMeasFitter.md create mode 100644 docs/api/qiskit/0.46/qiskit.utils.mitigation.TensoredMeasFitter.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.array_to_latex.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.circuit.qcstyle.DefaultStyle.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.circuit_drawer.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.dag_drawer.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.pass_manager_drawer.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_multivector.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_vector.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_circuit_layout.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_coupling_map.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_distribution.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_error_map.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_gate_map.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_histogram.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_state_city.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_state_hinton.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_state_paulivec.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.plot_state_qsphere.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXDebugging.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXSimple.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXStandard.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.pulse_drawer.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.timeline_drawer.md create mode 100644 docs/api/qiskit/0.46/qiskit.visualization.visualize_transition.md create mode 100644 docs/api/qiskit/0.46/qobj.md create mode 100644 docs/api/qiskit/0.46/qpy.md create mode 100644 docs/api/qiskit/0.46/quantum_info.md create mode 100644 docs/api/qiskit/0.46/result.md create mode 100644 docs/api/qiskit/0.46/scheduler.md create mode 100644 docs/api/qiskit/0.46/synthesis.md create mode 100644 docs/api/qiskit/0.46/synthesis_aqc.md create mode 100644 docs/api/qiskit/0.46/tools.md create mode 100644 docs/api/qiskit/0.46/tools_jupyter.md create mode 100644 docs/api/qiskit/0.46/transpiler.md create mode 100644 docs/api/qiskit/0.46/transpiler_builtin_plugins.md create mode 100644 docs/api/qiskit/0.46/transpiler_passes.md create mode 100644 docs/api/qiskit/0.46/transpiler_plugins.md create mode 100644 docs/api/qiskit/0.46/transpiler_preset.md create mode 100644 docs/api/qiskit/0.46/transpiler_synthesis_plugins.md create mode 100644 docs/api/qiskit/0.46/utils.md create mode 100644 docs/api/qiskit/0.46/utils_mitigation.md create mode 100644 docs/api/qiskit/0.46/visualization.md create mode 100644 public/images/api/qiskit/0.46/circuit-1.png create mode 100644 public/images/api/qiskit/0.46/circuit-2.png create mode 100644 public/images/api/qiskit/0.46/circuit-3.png create mode 100644 public/images/api/qiskit/0.46/circuit-4.png create mode 100644 public/images/api/qiskit/0.46/circuit-5.png create mode 100644 public/images/api/qiskit/0.46/circuit_library-1.png create mode 100644 public/images/api/qiskit/0.46/converters-1.png create mode 100644 public/images/api/qiskit/0.46/depth.gif create mode 100644 public/images/api/qiskit/0.46/mapping.png create mode 100644 public/images/api/qiskit/0.46/providers_fake_provider-1_00.png create mode 100644 public/images/api/qiskit/0.46/providers_fake_provider-1_01.png create mode 100644 public/images/api/qiskit/0.46/providers_fake_provider-1_02.png create mode 100644 public/images/api/qiskit/0.46/pulse-1.png create mode 100644 public/images/api/qiskit/0.46/pulse-2.png create mode 100644 public/images/api/qiskit/0.46/pulse-3.png create mode 100644 public/images/api/qiskit/0.46/pulse-4.png create mode 100644 public/images/api/qiskit/0.46/pulse-5.png create mode 100644 public/images/api/qiskit/0.46/pulse-6.png create mode 100644 public/images/api/qiskit/0.46/pulse-7.png create mode 100644 public/images/api/qiskit/0.46/pulse-8.png create mode 100644 public/images/api/qiskit/0.46/pulse-9.png create mode 100644 public/images/api/qiskit/0.46/qasm3-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-ControlledGate-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-ControlledGate-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-InstructionSet-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-Operation-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-Parameter-1_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-Parameter-1_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-3_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-3_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-4_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-4_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-5.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-6.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-AND-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-AND-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-FourierChecking-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-GMS-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-GR-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-GRX-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-GRY-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-GRZ-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-GraphState-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-HiddenLinearFunction-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-IQP-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-IQP-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-InnerProduct-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-MCMTVChain-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-OR-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-OR-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-PauliTwoDesign-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-Permutation-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-Permutation-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-PermutationGate-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-PermutationGate-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-PhaseEstimation-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-PiecewiseChebyshev-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-QFT-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-QFT-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-QFT-3.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-QuantumVolume-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-QuantumVolume-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-circuit-library-XOR-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-pulse-library-SymbolicPulse-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-quantum_info-Statevector-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-transpiler-passes-DynamicalDecoupling-1_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-transpiler-passes-DynamicalDecoupling-1_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-transpiler-passes-PadDynamicalDecoupling-1_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-transpiler-passes-PadDynamicalDecoupling-1_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-transpiler-passes-RemoveBarriers-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-circuit_drawer-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_multivector-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_multivector-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_vector-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_vector-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_circuit_layout-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_coupling_map-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_distribution-1_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_distribution-1_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_distribution-1_02.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_error_map-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_gate_map-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_histogram-1_00.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_histogram-1_01.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_histogram-1_02.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_city-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_city-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_hinton-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_paulivec-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_paulivec-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_qsphere-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-plot_state_qsphere-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-pulse_drawer-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-pulse_drawer-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-pulse_drawer-3.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-timeline_drawer-1.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-timeline_drawer-2.png create mode 100644 public/images/api/qiskit/0.46/qiskit-visualization-timeline_drawer-3.png create mode 100644 public/images/api/qiskit/0.46/transpiler-10.png create mode 100644 public/images/api/qiskit/0.46/transpiler-11.png create mode 100644 public/images/api/qiskit/0.46/transpiler-12.png create mode 100644 public/images/api/qiskit/0.46/transpiler-13.png create mode 100644 public/images/api/qiskit/0.46/transpiler-14.png create mode 100644 public/images/api/qiskit/0.46/transpiler-15.png create mode 100644 public/images/api/qiskit/0.46/transpiler-16.png create mode 100644 public/images/api/qiskit/0.46/transpiler-17.png create mode 100644 public/images/api/qiskit/0.46/transpiler-4.png create mode 100644 public/images/api/qiskit/0.46/transpiler-5.png create mode 100644 public/images/api/qiskit/0.46/transpiler-6.png create mode 100644 public/images/api/qiskit/0.46/transpiler-7.png create mode 100644 public/images/api/qiskit/0.46/transpiler-8.png create mode 100644 public/images/api/qiskit/0.46/transpiler-9.png create mode 100644 public/images/api/qiskit/0.46/transpiling_core_steps.png create mode 100644 public/images/api/qiskit/0.46/visualization-1.png create mode 100644 public/images/api/qiskit/0.46/visualization-2.png create mode 100644 public/images/api/qiskit/0.46/visualization-3.png create mode 100644 public/images/api/qiskit/0.46/visualization-4.png create mode 100644 public/images/api/qiskit/0.46/visualization-5.png create mode 100644 public/images/api/qiskit/0.46/visualization-6.png diff --git a/docs/api/qiskit/0.46/_package.json b/docs/api/qiskit/0.46/_package.json new file mode 100644 index 00000000000..cfb4023267e --- /dev/null +++ b/docs/api/qiskit/0.46/_package.json @@ -0,0 +1,4 @@ +{ + "name": "qiskit", + "version": "0.46.0" +} diff --git a/docs/api/qiskit/0.46/_toc.json b/docs/api/qiskit/0.46/_toc.json new file mode 100644 index 00000000000..3bfafd17182 --- /dev/null +++ b/docs/api/qiskit/0.46/_toc.json @@ -0,0 +1,3633 @@ +{ + "title": "Qiskit", + "children": [ + { + "title": "qiskit", + "url": "/api/qiskit/0.46" + }, + { + "title": "qiskit.algorithms", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/algorithms" + }, + { + "title": "AlgorithmJob", + "url": "/api/qiskit/0.46/qiskit.algorithms.AlgorithmJob" + }, + { + "title": "AmplificationProblem", + "url": "/api/qiskit/0.46/qiskit.algorithms.AmplificationProblem" + }, + { + "title": "AmplitudeAmplifier", + "url": "/api/qiskit/0.46/qiskit.algorithms.AmplitudeAmplifier" + }, + { + "title": "AmplitudeEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimation" + }, + { + "title": "AmplitudeEstimationResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimationResult" + }, + { + "title": "AmplitudeEstimator", + "url": "/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimator" + }, + { + "title": "AmplitudeEstimatorResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimatorResult" + }, + { + "title": "Eigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.Eigensolver" + }, + { + "title": "EigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.EigensolverResult" + }, + { + "title": "EstimationProblem", + "url": "/api/qiskit/0.46/qiskit.algorithms.EstimationProblem" + }, + { + "title": "EvolutionProblem", + "url": "/api/qiskit/0.46/qiskit.algorithms.EvolutionProblem" + }, + { + "title": "EvolutionResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.EvolutionResult" + }, + { + "title": "FasterAmplitudeEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimation" + }, + { + "title": "FasterAmplitudeEstimationResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimationResult" + }, + { + "title": "Grover", + "url": "/api/qiskit/0.46/qiskit.algorithms.Grover" + }, + { + "title": "GroverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.GroverResult" + }, + { + "title": "HamiltonianPhaseEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimation" + }, + { + "title": "HamiltonianPhaseEstimationResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimationResult" + }, + { + "title": "ImaginaryEvolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.ImaginaryEvolver" + }, + { + "title": "ImaginaryTimeEvolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.ImaginaryTimeEvolver" + }, + { + "title": "IterativeAmplitudeEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimation" + }, + { + "title": "IterativeAmplitudeEstimationResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimationResult" + }, + { + "title": "IterativePhaseEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.IterativePhaseEstimation" + }, + { + "title": "MaximumLikelihoodAmplitudeEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation" + }, + { + "title": "MaximumLikelihoodAmplitudeEstimationResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult" + }, + { + "title": "MinimumEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolver" + }, + { + "title": "MinimumEigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolverResult" + }, + { + "title": "NumPyEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.NumPyEigensolver" + }, + { + "title": "NumPyMinimumEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.NumPyMinimumEigensolver" + }, + { + "title": "PhaseEstimation", + "url": "/api/qiskit/0.46/qiskit.algorithms.PhaseEstimation" + }, + { + "title": "PhaseEstimationResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationResult" + }, + { + "title": "PhaseEstimationScale", + "url": "/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationScale" + }, + { + "title": "PVQD", + "url": "/api/qiskit/0.46/qiskit.algorithms.PVQD" + }, + { + "title": "PVQDResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.PVQDResult" + }, + { + "title": "QAOA", + "url": "/api/qiskit/0.46/qiskit.algorithms.QAOA" + }, + { + "title": "RealEvolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.RealEvolver" + }, + { + "title": "RealTimeEvolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.RealTimeEvolver" + }, + { + "title": "SciPyImaginaryEvolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.SciPyImaginaryEvolver" + }, + { + "title": "SciPyRealEvolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.SciPyRealEvolver" + }, + { + "title": "TimeEvolutionProblem", + "url": "/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionProblem" + }, + { + "title": "TimeEvolutionResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionResult" + }, + { + "title": "TrotterQRTE", + "url": "/api/qiskit/0.46/qiskit.algorithms.TrotterQRTE" + }, + { + "title": "VarQITE", + "url": "/api/qiskit/0.46/qiskit.algorithms.VarQITE" + }, + { + "title": "VarQRTE", + "url": "/api/qiskit/0.46/qiskit.algorithms.VarQRTE" + }, + { + "title": "VQD", + "url": "/api/qiskit/0.46/qiskit.algorithms.VQD" + }, + { + "title": "VQDResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.VQDResult" + }, + { + "title": "VQE", + "url": "/api/qiskit/0.46/qiskit.algorithms.VQE" + }, + { + "title": "qiskit.algorithms.eigensolvers", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers" + }, + { + "title": "Eigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers.Eigensolver" + }, + { + "title": "EigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers.EigensolverResult" + }, + { + "title": "NumPyEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolver" + }, + { + "title": "NumPyEigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolverResult" + }, + { + "title": "VQD", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQD" + }, + { + "title": "VQDResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQDResult" + } + ] + }, + { + "title": "qiskit.algorithms.gradients", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients" + }, + { + "title": "BaseEstimatorGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.BaseEstimatorGradient" + }, + { + "title": "BaseQGT", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.BaseQGT" + }, + { + "title": "BaseSamplerGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.BaseSamplerGradient" + }, + { + "title": "EstimatorGradientResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.EstimatorGradientResult" + }, + { + "title": "FiniteDiffEstimatorGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffEstimatorGradient" + }, + { + "title": "FiniteDiffSamplerGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffSamplerGradient" + }, + { + "title": "LinCombEstimatorGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombEstimatorGradient" + }, + { + "title": "LinCombQGT", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombQGT" + }, + { + "title": "LinCombSamplerGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombSamplerGradient" + }, + { + "title": "ParamShiftEstimatorGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftEstimatorGradient" + }, + { + "title": "ParamShiftSamplerGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftSamplerGradient" + }, + { + "title": "QFI", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.QFI" + }, + { + "title": "QFIResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.QFIResult" + }, + { + "title": "QGTResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.QGTResult" + }, + { + "title": "ReverseEstimatorGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseEstimatorGradient" + }, + { + "title": "ReverseQGT", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseQGT" + }, + { + "title": "SamplerGradientResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.SamplerGradientResult" + }, + { + "title": "SPSAEstimatorGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.SPSAEstimatorGradient" + }, + { + "title": "SPSASamplerGradient", + "url": "/api/qiskit/0.46/qiskit.algorithms.gradients.SPSASamplerGradient" + } + ] + }, + { + "title": "qiskit.algorithms.minimum_eigensolvers", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers" + }, + { + "title": "AdaptVQE", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQE" + }, + { + "title": "AdaptVQEResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult" + }, + { + "title": "MinimumEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver" + }, + { + "title": "MinimumEigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult" + }, + { + "title": "NumPyMinimumEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver" + }, + { + "title": "NumPyMinimumEigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult" + }, + { + "title": "QAOA", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.QAOA" + }, + { + "title": "SamplingMinimumEigensolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver" + }, + { + "title": "SamplingMinimumEigensolverResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult" + }, + { + "title": "SamplingVQE", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQE" + }, + { + "title": "SamplingVQEResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult" + }, + { + "title": "VQE", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQE" + }, + { + "title": "VQEResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQEResult" + } + ] + }, + { + "title": "qiskit.algorithms.optimizers", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers" + }, + { + "title": "ADAM", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.ADAM" + }, + { + "title": "AQGD", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.AQGD" + }, + { + "title": "AskData", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.AskData" + }, + { + "title": "BOBYQA", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.BOBYQA" + }, + { + "title": "CG", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.CG" + }, + { + "title": "COBYLA", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.COBYLA" + }, + { + "title": "CRS", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.CRS" + }, + { + "title": "DIRECT_L", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L" + }, + { + "title": "DIRECT_L_RAND", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L_RAND" + }, + { + "title": "ESCH", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.ESCH" + }, + { + "title": "GradientDescent", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescent" + }, + { + "title": "GradientDescentState", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescentState" + }, + { + "title": "GSLS", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.GSLS" + }, + { + "title": "IMFIL", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.IMFIL" + }, + { + "title": "ISRES", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.ISRES" + }, + { + "title": "L_BFGS_B", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.L_BFGS_B" + }, + { + "title": "Minimizer", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.Minimizer" + }, + { + "title": "NELDER_MEAD", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.NELDER_MEAD" + }, + { + "title": "NFT", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.NFT" + }, + { + "title": "Optimizer", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.Optimizer" + }, + { + "title": "OptimizerResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerResult" + }, + { + "title": "OptimizerState", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerState" + }, + { + "title": "OptimizerSupportLevel", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerSupportLevel" + }, + { + "title": "P_BFGS", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.P_BFGS" + }, + { + "title": "POWELL", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.POWELL" + }, + { + "title": "QNSPSA", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.QNSPSA" + }, + { + "title": "SciPyOptimizer", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.SciPyOptimizer" + }, + { + "title": "SLSQP", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.SLSQP" + }, + { + "title": "SNOBFIT", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.SNOBFIT" + }, + { + "title": "SPSA", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.SPSA" + }, + { + "title": "SteppableOptimizer", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.SteppableOptimizer" + }, + { + "title": "TellData", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.TellData" + }, + { + "title": "TNC", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.TNC" + }, + { + "title": "UMDA", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.UMDA" + }, + { + "title": "qiskit.algorithms.optimizers.optimizer_utils", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils" + }, + { + "title": "LearningRate", + "url": "/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.LearningRate" + } + ] + } + ] + }, + { + "title": "qiskit.algorithms.state_fidelities", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.state_fidelities" + }, + { + "title": "BaseStateFidelity", + "url": "/api/qiskit/0.46/qiskit.algorithms.state_fidelities.BaseStateFidelity" + }, + { + "title": "ComputeUncompute", + "url": "/api/qiskit/0.46/qiskit.algorithms.state_fidelities.ComputeUncompute" + }, + { + "title": "StateFidelityResult", + "url": "/api/qiskit/0.46/qiskit.algorithms.state_fidelities.StateFidelityResult" + } + ] + }, + { + "title": "qiskit.algorithms.time_evolvers.trotterization", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization" + }, + { + "title": "TrotterQRTE", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE" + } + ] + }, + { + "title": "qiskit.algorithms.time_evolvers.variational", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational" + }, + { + "title": "ForwardEulerSolver", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver" + }, + { + "title": "ImaginaryMcLachlanPrinciple", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple" + }, + { + "title": "ImaginaryVariationalPrinciple", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple" + }, + { + "title": "RealMcLachlanPrinciple", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple" + }, + { + "title": "RealVariationalPrinciple", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple" + }, + { + "title": "VariationalPrinciple", + "url": "/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.VariationalPrinciple" + } + ] + } + ] + }, + { + "title": "qiskit.assembler", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/assembler" + }, + { + "title": "RunConfig", + "url": "/api/qiskit/0.46/qiskit.assembler.RunConfig" + } + ] + }, + { + "title": "qiskit.circuit", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/circuit" + }, + { + "title": "AncillaQubit", + "url": "/api/qiskit/0.46/qiskit.circuit.AncillaQubit" + }, + { + "title": "AncillaRegister", + "url": "/api/qiskit/0.46/qiskit.circuit.AncillaRegister" + }, + { + "title": "AnnotatedOperation", + "url": "/api/qiskit/0.46/qiskit.circuit.AnnotatedOperation" + }, + { + "title": "Bit", + "url": "/api/qiskit/0.46/qiskit.circuit.Bit" + }, + { + "title": "BreakLoopOp", + "url": "/api/qiskit/0.46/qiskit.circuit.BreakLoopOp" + }, + { + "title": "CircuitInstruction", + "url": "/api/qiskit/0.46/qiskit.circuit.CircuitInstruction" + }, + { + "title": "ClassicalRegister", + "url": "/api/qiskit/0.46/qiskit.circuit.ClassicalRegister" + }, + { + "title": "Clbit", + "url": "/api/qiskit/0.46/qiskit.circuit.Clbit" + }, + { + "title": "CommutationChecker", + "url": "/api/qiskit/0.46/qiskit.circuit.CommutationChecker" + }, + { + "title": "ContinueLoopOp", + "url": "/api/qiskit/0.46/qiskit.circuit.ContinueLoopOp" + }, + { + "title": "ControlFlowOp", + "url": "/api/qiskit/0.46/qiskit.circuit.ControlFlowOp" + }, + { + "title": "ControlledGate", + "url": "/api/qiskit/0.46/qiskit.circuit.ControlledGate" + }, + { + "title": "ControlModifier", + "url": "/api/qiskit/0.46/qiskit.circuit.ControlModifier" + }, + { + "title": "Delay", + "url": "/api/qiskit/0.46/qiskit.circuit.Delay" + }, + { + "title": "EquivalenceLibrary", + "url": "/api/qiskit/0.46/qiskit.circuit.EquivalenceLibrary" + }, + { + "title": "ForLoopOp", + "url": "/api/qiskit/0.46/qiskit.circuit.ForLoopOp" + }, + { + "title": "Gate", + "url": "/api/qiskit/0.46/qiskit.circuit.Gate" + }, + { + "title": "IfElseOp", + "url": "/api/qiskit/0.46/qiskit.circuit.IfElseOp" + }, + { + "title": "Instruction", + "url": "/api/qiskit/0.46/qiskit.circuit.Instruction" + }, + { + "title": "InstructionSet", + "url": "/api/qiskit/0.46/qiskit.circuit.InstructionSet" + }, + { + "title": "InverseModifier", + "url": "/api/qiskit/0.46/qiskit.circuit.InverseModifier" + }, + { + "title": "Operation", + "url": "/api/qiskit/0.46/qiskit.circuit.Operation" + }, + { + "title": "Parameter", + "url": "/api/qiskit/0.46/qiskit.circuit.Parameter" + }, + { + "title": "ParameterExpression", + "url": "/api/qiskit/0.46/qiskit.circuit.ParameterExpression" + }, + { + "title": "ParameterVector", + "url": "/api/qiskit/0.46/qiskit.circuit.ParameterVector" + }, + { + "title": "PowerModifier", + "url": "/api/qiskit/0.46/qiskit.circuit.PowerModifier" + }, + { + "title": "qiskit.circuit.classical", + "url": "/api/qiskit/0.46/circuit_classical" + }, + { + "title": "qiskit.circuit.singleton", + "url": "/api/qiskit/0.46/circuit_singleton" + }, + { + "title": "QuantumCircuit", + "url": "/api/qiskit/0.46/qiskit.circuit.QuantumCircuit" + }, + { + "title": "QuantumRegister", + "url": "/api/qiskit/0.46/qiskit.circuit.QuantumRegister" + }, + { + "title": "Qubit", + "url": "/api/qiskit/0.46/qiskit.circuit.Qubit" + }, + { + "title": "Register", + "url": "/api/qiskit/0.46/qiskit.circuit.Register" + }, + { + "title": "SwitchCaseOp", + "url": "/api/qiskit/0.46/qiskit.circuit.SwitchCaseOp" + }, + { + "title": "WhileLoopOp", + "url": "/api/qiskit/0.46/qiskit.circuit.WhileLoopOp" + }, + { + "title": "qiskit.circuit.classicalfunction", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/classicalfunction" + }, + { + "title": "BooleanExpression", + "url": "/api/qiskit/0.46/qiskit.circuit.classicalfunction.BooleanExpression" + }, + { + "title": "ClassicalFunction", + "url": "/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunction" + }, + { + "title": "ClassicalFunctionCompilerTypeError", + "url": "/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError" + }, + { + "title": "ClassicalFunctionParseError", + "url": "/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionParseError" + } + ] + }, + { + "title": "qiskit.circuit.library", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/circuit_library" + }, + { + "title": "AND", + "url": "/api/qiskit/0.46/qiskit.circuit.library.AND" + }, + { + "title": "Barrier", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Barrier" + }, + { + "title": "C3SXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.C3SXGate" + }, + { + "title": "C3XGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.C3XGate" + }, + { + "title": "C4XGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.C4XGate" + }, + { + "title": "CCXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CCXGate" + }, + { + "title": "CCZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CCZGate" + }, + { + "title": "CDKMRippleCarryAdder", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CDKMRippleCarryAdder" + }, + { + "title": "CHGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CHGate" + }, + { + "title": "CPhaseGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CPhaseGate" + }, + { + "title": "CRXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CRXGate" + }, + { + "title": "CRYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CRYGate" + }, + { + "title": "CRZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CRZGate" + }, + { + "title": "CSdgGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CSdgGate" + }, + { + "title": "CSGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CSGate" + }, + { + "title": "CSwapGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CSwapGate" + }, + { + "title": "CSXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CSXGate" + }, + { + "title": "CU1Gate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CU1Gate" + }, + { + "title": "CU3Gate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CU3Gate" + }, + { + "title": "CUGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CUGate" + }, + { + "title": "CXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CXGate" + }, + { + "title": "CYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CYGate" + }, + { + "title": "CZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.CZGate" + }, + { + "title": "DCXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.DCXGate" + }, + { + "title": "Diagonal", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Diagonal" + }, + { + "title": "DiagonalGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.DiagonalGate" + }, + { + "title": "DraperQFTAdder", + "url": "/api/qiskit/0.46/qiskit.circuit.library.DraperQFTAdder" + }, + { + "title": "ECRGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.ECRGate" + }, + { + "title": "EfficientSU2", + "url": "/api/qiskit/0.46/qiskit.circuit.library.EfficientSU2" + }, + { + "title": "EvolvedOperatorAnsatz", + "url": "/api/qiskit/0.46/qiskit.circuit.library.EvolvedOperatorAnsatz" + }, + { + "title": "ExactReciprocal", + "url": "/api/qiskit/0.46/qiskit.circuit.library.ExactReciprocal" + }, + { + "title": "ExcitationPreserving", + "url": "/api/qiskit/0.46/qiskit.circuit.library.ExcitationPreserving" + }, + { + "title": "FourierChecking", + "url": "/api/qiskit/0.46/qiskit.circuit.library.FourierChecking" + }, + { + "title": "FunctionalPauliRotations", + "url": "/api/qiskit/0.46/qiskit.circuit.library.FunctionalPauliRotations" + }, + { + "title": "GlobalPhaseGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GlobalPhaseGate" + }, + { + "title": "GMS", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GMS" + }, + { + "title": "GR", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GR" + }, + { + "title": "GraphState", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GraphState" + }, + { + "title": "GroverOperator", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GroverOperator" + }, + { + "title": "GRX", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GRX" + }, + { + "title": "GRY", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GRY" + }, + { + "title": "GRZ", + "url": "/api/qiskit/0.46/qiskit.circuit.library.GRZ" + }, + { + "title": "HamiltonianGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.HamiltonianGate" + }, + { + "title": "HGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.HGate" + }, + { + "title": "HiddenLinearFunction", + "url": "/api/qiskit/0.46/qiskit.circuit.library.HiddenLinearFunction" + }, + { + "title": "HRSCumulativeMultiplier", + "url": "/api/qiskit/0.46/qiskit.circuit.library.HRSCumulativeMultiplier" + }, + { + "title": "IGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.IGate" + }, + { + "title": "Initialize", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Initialize" + }, + { + "title": "InnerProduct", + "url": "/api/qiskit/0.46/qiskit.circuit.library.InnerProduct" + }, + { + "title": "IntegerComparator", + "url": "/api/qiskit/0.46/qiskit.circuit.library.IntegerComparator" + }, + { + "title": "IQP", + "url": "/api/qiskit/0.46/qiskit.circuit.library.IQP" + }, + { + "title": "Isometry", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Isometry" + }, + { + "title": "iSwapGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.iSwapGate" + }, + { + "title": "LinearAmplitudeFunction", + "url": "/api/qiskit/0.46/qiskit.circuit.library.LinearAmplitudeFunction" + }, + { + "title": "LinearFunction", + "url": "/api/qiskit/0.46/qiskit.circuit.library.LinearFunction" + }, + { + "title": "LinearPauliRotations", + "url": "/api/qiskit/0.46/qiskit.circuit.library.LinearPauliRotations" + }, + { + "title": "MCMT", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCMT" + }, + { + "title": "MCMTVChain", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCMTVChain" + }, + { + "title": "MCPhaseGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCPhaseGate" + }, + { + "title": "MCXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCXGate" + }, + { + "title": "MCXGrayCode", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCXGrayCode" + }, + { + "title": "MCXRecursive", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCXRecursive" + }, + { + "title": "MCXVChain", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MCXVChain" + }, + { + "title": "Measure", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Measure" + }, + { + "title": "MSGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.MSGate" + }, + { + "title": "NLocal", + "url": "/api/qiskit/0.46/qiskit.circuit.library.NLocal" + }, + { + "title": "OR", + "url": "/api/qiskit/0.46/qiskit.circuit.library.OR" + }, + { + "title": "PauliEvolutionGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PauliEvolutionGate" + }, + { + "title": "PauliFeatureMap", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PauliFeatureMap" + }, + { + "title": "PauliGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PauliGate" + }, + { + "title": "PauliTwoDesign", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PauliTwoDesign" + }, + { + "title": "Permutation", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Permutation" + }, + { + "title": "PermutationGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PermutationGate" + }, + { + "title": "PhaseEstimation", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PhaseEstimation" + }, + { + "title": "PhaseGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PhaseGate" + }, + { + "title": "PhaseOracle", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PhaseOracle" + }, + { + "title": "PiecewiseChebyshev", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PiecewiseChebyshev" + }, + { + "title": "PiecewiseLinearPauliRotations", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PiecewiseLinearPauliRotations" + }, + { + "title": "PiecewisePolynomialPauliRotations", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PiecewisePolynomialPauliRotations" + }, + { + "title": "PolynomialPauliRotations", + "url": "/api/qiskit/0.46/qiskit.circuit.library.PolynomialPauliRotations" + }, + { + "title": "QAOAAnsatz", + "url": "/api/qiskit/0.46/qiskit.circuit.library.QAOAAnsatz" + }, + { + "title": "QFT", + "url": "/api/qiskit/0.46/qiskit.circuit.library.QFT" + }, + { + "title": "QuadraticForm", + "url": "/api/qiskit/0.46/qiskit.circuit.library.QuadraticForm" + }, + { + "title": "QuantumVolume", + "url": "/api/qiskit/0.46/qiskit.circuit.library.QuantumVolume" + }, + { + "title": "RC3XGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RC3XGate" + }, + { + "title": "RCCXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RCCXGate" + }, + { + "title": "RealAmplitudes", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RealAmplitudes" + }, + { + "title": "Reset", + "url": "/api/qiskit/0.46/qiskit.circuit.library.Reset" + }, + { + "title": "RGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RGate" + }, + { + "title": "RGQFTMultiplier", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RGQFTMultiplier" + }, + { + "title": "RVGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RVGate" + }, + { + "title": "RXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RXGate" + }, + { + "title": "RXXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RXXGate" + }, + { + "title": "RYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RYGate" + }, + { + "title": "RYYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RYYGate" + }, + { + "title": "RZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RZGate" + }, + { + "title": "RZXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RZXGate" + }, + { + "title": "RZZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.RZZGate" + }, + { + "title": "SdgGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.SdgGate" + }, + { + "title": "SGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.SGate" + }, + { + "title": "StatePreparation", + "url": "/api/qiskit/0.46/qiskit.circuit.library.StatePreparation" + }, + { + "title": "SwapGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.SwapGate" + }, + { + "title": "SXdgGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.SXdgGate" + }, + { + "title": "SXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.SXGate" + }, + { + "title": "TdgGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.TdgGate" + }, + { + "title": "TGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.TGate" + }, + { + "title": "TwoLocal", + "url": "/api/qiskit/0.46/qiskit.circuit.library.TwoLocal" + }, + { + "title": "U1Gate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.U1Gate" + }, + { + "title": "U2Gate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.U2Gate" + }, + { + "title": "U3Gate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.U3Gate" + }, + { + "title": "UCGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UCGate" + }, + { + "title": "UCPauliRotGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UCPauliRotGate" + }, + { + "title": "UCRXGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UCRXGate" + }, + { + "title": "UCRYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UCRYGate" + }, + { + "title": "UCRZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UCRZGate" + }, + { + "title": "UGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UGate" + }, + { + "title": "UnitaryGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UnitaryGate" + }, + { + "title": "UnitaryOverlap", + "url": "/api/qiskit/0.46/qiskit.circuit.library.UnitaryOverlap" + }, + { + "title": "VBERippleCarryAdder", + "url": "/api/qiskit/0.46/qiskit.circuit.library.VBERippleCarryAdder" + }, + { + "title": "WeightedAdder", + "url": "/api/qiskit/0.46/qiskit.circuit.library.WeightedAdder" + }, + { + "title": "XGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.XGate" + }, + { + "title": "XOR", + "url": "/api/qiskit/0.46/qiskit.circuit.library.XOR" + }, + { + "title": "XXMinusYYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.XXMinusYYGate" + }, + { + "title": "XXPlusYYGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.XXPlusYYGate" + }, + { + "title": "YGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.YGate" + }, + { + "title": "ZFeatureMap", + "url": "/api/qiskit/0.46/qiskit.circuit.library.ZFeatureMap" + }, + { + "title": "ZGate", + "url": "/api/qiskit/0.46/qiskit.circuit.library.ZGate" + }, + { + "title": "ZZFeatureMap", + "url": "/api/qiskit/0.46/qiskit.circuit.library.ZZFeatureMap" + } + ] + } + ] + }, + { + "title": "qiskit.compiler", + "url": "/api/qiskit/0.46/compiler" + }, + { + "title": "qiskit.converters", + "url": "/api/qiskit/0.46/converters" + }, + { + "title": "qiskit.dagcircuit", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/dagcircuit" + }, + { + "title": "DAGCircuit", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGCircuit" + }, + { + "title": "DAGDependency", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGDependency" + }, + { + "title": "DAGDepNode", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGDepNode" + }, + { + "title": "DAGInNode", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGInNode" + }, + { + "title": "DAGNode", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGNode" + }, + { + "title": "DAGOpNode", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGOpNode" + }, + { + "title": "DAGOutNode", + "url": "/api/qiskit/0.46/qiskit.dagcircuit.DAGOutNode" + } + ] + }, + { + "title": "qiskit.exceptions", + "url": "/api/qiskit/0.46/exceptions" + }, + { + "title": "qiskit.execute_function", + "url": "/api/qiskit/0.46/execute" + }, + { + "title": "qiskit.extensions", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/extensions" + }, + { + "title": "SingleQubitUnitary", + "url": "/api/qiskit/0.46/qiskit.extensions.SingleQubitUnitary" + }, + { + "title": "Snapshot", + "url": "/api/qiskit/0.46/qiskit.extensions.Snapshot" + } + ] + }, + { + "title": "qiskit.opflow", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/opflow" + }, + { + "title": "OperatorBase", + "url": "/api/qiskit/0.46/qiskit.opflow.OperatorBase" + }, + { + "title": "qiskit.opflow.converters", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.converters" + }, + { + "title": "AbelianGrouper", + "url": "/api/qiskit/0.46/qiskit.opflow.converters.AbelianGrouper" + }, + { + "title": "CircuitSampler", + "url": "/api/qiskit/0.46/qiskit.opflow.converters.CircuitSampler" + }, + { + "title": "ConverterBase", + "url": "/api/qiskit/0.46/qiskit.opflow.converters.ConverterBase" + }, + { + "title": "DictToCircuitSum", + "url": "/api/qiskit/0.46/qiskit.opflow.converters.DictToCircuitSum" + }, + { + "title": "PauliBasisChange", + "url": "/api/qiskit/0.46/qiskit.opflow.converters.PauliBasisChange" + }, + { + "title": "TwoQubitReduction", + "url": "/api/qiskit/0.46/qiskit.opflow.converters.TwoQubitReduction" + } + ] + }, + { + "title": "qiskit.opflow.evolutions", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions" + }, + { + "title": "EvolutionBase", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionBase" + }, + { + "title": "EvolutionFactory", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionFactory" + }, + { + "title": "EvolvedOp", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.EvolvedOp" + }, + { + "title": "MatrixEvolution", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.MatrixEvolution" + }, + { + "title": "PauliTrotterEvolution", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.PauliTrotterEvolution" + }, + { + "title": "QDrift", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.QDrift" + }, + { + "title": "Suzuki", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.Suzuki" + }, + { + "title": "Trotter", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.Trotter" + }, + { + "title": "TrotterizationBase", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationBase" + }, + { + "title": "TrotterizationFactory", + "url": "/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationFactory" + } + ] + }, + { + "title": "qiskit.opflow.expectations", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations" + }, + { + "title": "AerPauliExpectation", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations.AerPauliExpectation" + }, + { + "title": "CVaRExpectation", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations.CVaRExpectation" + }, + { + "title": "ExpectationBase", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationBase" + }, + { + "title": "ExpectationFactory", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationFactory" + }, + { + "title": "MatrixExpectation", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations.MatrixExpectation" + }, + { + "title": "PauliExpectation", + "url": "/api/qiskit/0.46/qiskit.opflow.expectations.PauliExpectation" + } + ] + }, + { + "title": "qiskit.opflow.gradients", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients" + }, + { + "title": "CircuitGradient", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.CircuitGradient" + }, + { + "title": "CircuitQFI", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.CircuitQFI" + }, + { + "title": "DerivativeBase", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.DerivativeBase" + }, + { + "title": "Gradient", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.Gradient" + }, + { + "title": "GradientBase", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.GradientBase" + }, + { + "title": "Hessian", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.Hessian" + }, + { + "title": "HessianBase", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.HessianBase" + }, + { + "title": "NaturalGradient", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.NaturalGradient" + }, + { + "title": "QFI", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.QFI" + }, + { + "title": "QFIBase", + "url": "/api/qiskit/0.46/qiskit.opflow.gradients.QFIBase" + } + ] + }, + { + "title": "qiskit.opflow.list_ops", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.list_ops" + }, + { + "title": "ComposedOp", + "url": "/api/qiskit/0.46/qiskit.opflow.list_ops.ComposedOp" + }, + { + "title": "ListOp", + "url": "/api/qiskit/0.46/qiskit.opflow.list_ops.ListOp" + }, + { + "title": "SummedOp", + "url": "/api/qiskit/0.46/qiskit.opflow.list_ops.SummedOp" + }, + { + "title": "TensoredOp", + "url": "/api/qiskit/0.46/qiskit.opflow.list_ops.TensoredOp" + } + ] + }, + { + "title": "qiskit.opflow.primitive_ops", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops" + }, + { + "title": "CircuitOp", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.CircuitOp" + }, + { + "title": "MatrixOp", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.MatrixOp" + }, + { + "title": "PauliOp", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliOp" + }, + { + "title": "PauliSumOp", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliSumOp" + }, + { + "title": "PrimitiveOp", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.PrimitiveOp" + }, + { + "title": "TaperedPauliSumOp", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.TaperedPauliSumOp" + }, + { + "title": "Z2Symmetries", + "url": "/api/qiskit/0.46/qiskit.opflow.primitive_ops.Z2Symmetries" + } + ] + }, + { + "title": "qiskit.opflow.state_fns", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns" + }, + { + "title": "CircuitStateFn", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.CircuitStateFn" + }, + { + "title": "CVaRMeasurement", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.CVaRMeasurement" + }, + { + "title": "DictStateFn", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.DictStateFn" + }, + { + "title": "OperatorStateFn", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.OperatorStateFn" + }, + { + "title": "SparseVectorStateFn", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.SparseVectorStateFn" + }, + { + "title": "StateFn", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.StateFn" + }, + { + "title": "VectorStateFn", + "url": "/api/qiskit/0.46/qiskit.opflow.state_fns.VectorStateFn" + } + ] + } + ] + }, + { + "title": "qiskit.passmanager", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/passmanager" + }, + { + "title": "BaseController", + "url": "/api/qiskit/0.46/qiskit.passmanager.BaseController" + }, + { + "title": "BasePassManager", + "url": "/api/qiskit/0.46/qiskit.passmanager.BasePassManager" + }, + { + "title": "ConditionalController", + "url": "/api/qiskit/0.46/qiskit.passmanager.ConditionalController" + }, + { + "title": "DoWhileController", + "url": "/api/qiskit/0.46/qiskit.passmanager.DoWhileController" + }, + { + "title": "FlowController", + "url": "/api/qiskit/0.46/qiskit.passmanager.FlowController" + }, + { + "title": "FlowControllerLinear", + "url": "/api/qiskit/0.46/qiskit.passmanager.FlowControllerLinear" + }, + { + "title": "GenericPass", + "url": "/api/qiskit/0.46/qiskit.passmanager.GenericPass" + }, + { + "title": "PassManagerState", + "url": "/api/qiskit/0.46/qiskit.passmanager.PassManagerState" + }, + { + "title": "PropertySet", + "url": "/api/qiskit/0.46/qiskit.passmanager.PropertySet" + }, + { + "title": "WorkflowStatus", + "url": "/api/qiskit/0.46/qiskit.passmanager.WorkflowStatus" + } + ] + }, + { + "title": "qiskit.primitives", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/primitives" + }, + { + "title": "BackendEstimator", + "url": "/api/qiskit/0.46/qiskit.primitives.BackendEstimator" + }, + { + "title": "BackendSampler", + "url": "/api/qiskit/0.46/qiskit.primitives.BackendSampler" + }, + { + "title": "BaseEstimator", + "url": "/api/qiskit/0.46/qiskit.primitives.BaseEstimator" + }, + { + "title": "BaseSampler", + "url": "/api/qiskit/0.46/qiskit.primitives.BaseSampler" + }, + { + "title": "Estimator", + "url": "/api/qiskit/0.46/qiskit.primitives.Estimator" + }, + { + "title": "EstimatorResult", + "url": "/api/qiskit/0.46/qiskit.primitives.EstimatorResult" + }, + { + "title": "Sampler", + "url": "/api/qiskit/0.46/qiskit.primitives.Sampler" + }, + { + "title": "SamplerResult", + "url": "/api/qiskit/0.46/qiskit.primitives.SamplerResult" + } + ] + }, + { + "title": "qiskit.providers", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/providers" + }, + { + "title": "Backend", + "url": "/api/qiskit/0.46/qiskit.providers.Backend" + }, + { + "title": "BackendV1", + "url": "/api/qiskit/0.46/qiskit.providers.BackendV1" + }, + { + "title": "BackendV2", + "url": "/api/qiskit/0.46/qiskit.providers.BackendV2" + }, + { + "title": "BackendV2Converter", + "url": "/api/qiskit/0.46/qiskit.providers.BackendV2Converter" + }, + { + "title": "convert_to_target", + "url": "/api/qiskit/0.46/qiskit.providers.convert_to_target" + }, + { + "title": "Job", + "url": "/api/qiskit/0.46/qiskit.providers.Job" + }, + { + "title": "JobStatus", + "url": "/api/qiskit/0.46/qiskit.providers.JobStatus" + }, + { + "title": "JobV1", + "url": "/api/qiskit/0.46/qiskit.providers.JobV1" + }, + { + "title": "Options", + "url": "/api/qiskit/0.46/qiskit.providers.Options" + }, + { + "title": "Provider", + "url": "/api/qiskit/0.46/qiskit.providers.Provider" + }, + { + "title": "ProviderV1", + "url": "/api/qiskit/0.46/qiskit.providers.ProviderV1" + }, + { + "title": "QubitProperties", + "url": "/api/qiskit/0.46/qiskit.providers.QubitProperties" + }, + { + "title": "qiskit.providers.basic_provider", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/providers_basic_provider" + }, + { + "title": "BasicProvider", + "url": "/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProvider" + }, + { + "title": "BasicProviderError", + "url": "/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderError" + }, + { + "title": "BasicProviderJob", + "url": "/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderJob" + }, + { + "title": "BasicSimulator", + "url": "/api/qiskit/0.46/qiskit.providers.basic_provider.BasicSimulator" + } + ] + }, + { + "title": "qiskit.providers.basicaer", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/providers_basicaer" + }, + { + "title": "BasicAerError", + "url": "/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerError" + }, + { + "title": "BasicAerJob", + "url": "/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerJob" + }, + { + "title": "BasicAerProvider", + "url": "/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerProvider" + }, + { + "title": "QasmSimulatorPy", + "url": "/api/qiskit/0.46/qiskit.providers.basicaer.QasmSimulatorPy" + }, + { + "title": "StatevectorSimulatorPy", + "url": "/api/qiskit/0.46/qiskit.providers.basicaer.StatevectorSimulatorPy" + }, + { + "title": "UnitarySimulatorPy", + "url": "/api/qiskit/0.46/qiskit.providers.basicaer.UnitarySimulatorPy" + } + ] + }, + { + "title": "qiskit.providers.fake_provider", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/providers_fake_provider" + }, + { + "title": "ConfigurableFakeBackend", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.ConfigurableFakeBackend" + }, + { + "title": "Fake1Q", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.Fake1Q" + }, + { + "title": "FakeAlmaden", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmaden" + }, + { + "title": "FakeAlmadenV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmadenV2" + }, + { + "title": "FakeArmonk", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonk" + }, + { + "title": "FakeArmonkV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonkV2" + }, + { + "title": "FakeAthens", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthens" + }, + { + "title": "FakeAthensV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthensV2" + }, + { + "title": "FakeAuckland", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAuckland" + }, + { + "title": "FakeBackend5QV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackend5QV2" + }, + { + "title": "FakeBackendV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackendV2" + }, + { + "title": "FakeBelem", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelem" + }, + { + "title": "FakeBelemV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelemV2" + }, + { + "title": "FakeBoeblingen", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingen" + }, + { + "title": "FakeBoeblingenV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingenV2" + }, + { + "title": "FakeBogota", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogota" + }, + { + "title": "FakeBogotaV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogotaV2" + }, + { + "title": "FakeBrooklyn", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklyn" + }, + { + "title": "FakeBrooklynV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklynV2" + }, + { + "title": "FakeBurlington", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlington" + }, + { + "title": "FakeBurlingtonV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlingtonV2" + }, + { + "title": "FakeCairo", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairo" + }, + { + "title": "FakeCairoV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairoV2" + }, + { + "title": "FakeCambridge", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridge" + }, + { + "title": "FakeCambridgeV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridgeV2" + }, + { + "title": "FakeCasablanca", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablanca" + }, + { + "title": "FakeCasablancaV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablancaV2" + }, + { + "title": "FakeEssex", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssex" + }, + { + "title": "FakeEssexV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssexV2" + }, + { + "title": "FakeGeneva", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGeneva" + }, + { + "title": "FakeGuadalupe", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupe" + }, + { + "title": "FakeGuadalupeV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupeV2" + }, + { + "title": "FakeHanoi", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoi" + }, + { + "title": "FakeHanoiV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoiV2" + }, + { + "title": "FakeJakarta", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakarta" + }, + { + "title": "FakeJakartaV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakartaV2" + }, + { + "title": "FakeJohannesburg", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburg" + }, + { + "title": "FakeJohannesburgV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburgV2" + }, + { + "title": "FakeKolkata", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkata" + }, + { + "title": "FakeKolkataV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkataV2" + }, + { + "title": "FakeLagos", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagos" + }, + { + "title": "FakeLagosV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagosV2" + }, + { + "title": "FakeLima", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLima" + }, + { + "title": "FakeLimaV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLimaV2" + }, + { + "title": "FakeLondon", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondon" + }, + { + "title": "FakeLondonV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondonV2" + }, + { + "title": "FakeManhattan", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattan" + }, + { + "title": "FakeManhattanV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattanV2" + }, + { + "title": "FakeManila", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManila" + }, + { + "title": "FakeManilaV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManilaV2" + }, + { + "title": "FakeMelbourne", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourne" + }, + { + "title": "FakeMelbourneV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourneV2" + }, + { + "title": "FakeMontreal", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontreal" + }, + { + "title": "FakeMontrealV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontrealV2" + }, + { + "title": "FakeMumbai", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbai" + }, + { + "title": "FakeMumbaiFractionalCX", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiFractionalCX" + }, + { + "title": "FakeMumbaiV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiV2" + }, + { + "title": "FakeNairobi", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobi" + }, + { + "title": "FakeNairobiV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobiV2" + }, + { + "title": "FakeOpenPulse2Q", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse2Q" + }, + { + "title": "FakeOpenPulse3Q", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse3Q" + }, + { + "title": "FakeOslo", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOslo" + }, + { + "title": "FakeOurense", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurense" + }, + { + "title": "FakeOurenseV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurenseV2" + }, + { + "title": "FakeParis", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParis" + }, + { + "title": "FakeParisV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParisV2" + }, + { + "title": "FakePerth", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakePerth" + }, + { + "title": "FakePoughkeepsie", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsie" + }, + { + "title": "FakePoughkeepsieV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsieV2" + }, + { + "title": "FakePrague", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakePrague" + }, + { + "title": "FakeProvider", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProvider" + }, + { + "title": "FakeProviderForBackendV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProviderForBackendV2" + }, + { + "title": "FakeQasmSimulator", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQasmSimulator" + }, + { + "title": "FakeQuito", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuito" + }, + { + "title": "FakeQuitoV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuitoV2" + }, + { + "title": "FakeRochester", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochester" + }, + { + "title": "FakeRochesterV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochesterV2" + }, + { + "title": "FakeRome", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRome" + }, + { + "title": "FakeRomeV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRomeV2" + }, + { + "title": "FakeRueschlikon", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRueschlikon" + }, + { + "title": "FakeSantiago", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiago" + }, + { + "title": "FakeSantiagoV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiagoV2" + }, + { + "title": "FakeSherbrooke", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSherbrooke" + }, + { + "title": "FakeSingapore", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingapore" + }, + { + "title": "FakeSingaporeV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingaporeV2" + }, + { + "title": "FakeSydney", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydney" + }, + { + "title": "FakeSydneyV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydneyV2" + }, + { + "title": "FakeTenerife", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTenerife" + }, + { + "title": "FakeTokyo", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTokyo" + }, + { + "title": "FakeToronto", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeToronto" + }, + { + "title": "FakeTorontoV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTorontoV2" + }, + { + "title": "FakeValencia", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValencia" + }, + { + "title": "FakeValenciaV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValenciaV2" + }, + { + "title": "FakeVigo", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigo" + }, + { + "title": "FakeVigoV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigoV2" + }, + { + "title": "FakeWashington", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashington" + }, + { + "title": "FakeWashingtonV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashingtonV2" + }, + { + "title": "FakeYorktown", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktown" + }, + { + "title": "FakeYorktownV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktownV2" + }, + { + "title": "GenericBackendV2", + "url": "/api/qiskit/0.46/qiskit.providers.fake_provider.GenericBackendV2" + } + ] + }, + { + "title": "qiskit.providers.models", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/providers_models" + }, + { + "title": "BackendConfiguration", + "url": "/api/qiskit/0.46/qiskit.providers.models.BackendConfiguration" + }, + { + "title": "BackendProperties", + "url": "/api/qiskit/0.46/qiskit.providers.models.BackendProperties" + }, + { + "title": "BackendStatus", + "url": "/api/qiskit/0.46/qiskit.providers.models.BackendStatus" + }, + { + "title": "Command", + "url": "/api/qiskit/0.46/qiskit.providers.models.Command" + }, + { + "title": "GateConfig", + "url": "/api/qiskit/0.46/qiskit.providers.models.GateConfig" + }, + { + "title": "GateProperties", + "url": "/api/qiskit/0.46/qiskit.providers.models.GateProperties" + }, + { + "title": "JobStatus", + "url": "/api/qiskit/0.46/qiskit.providers.models.JobStatus" + }, + { + "title": "Nduv", + "url": "/api/qiskit/0.46/qiskit.providers.models.Nduv" + }, + { + "title": "PulseBackendConfiguration", + "url": "/api/qiskit/0.46/qiskit.providers.models.PulseBackendConfiguration" + }, + { + "title": "PulseDefaults", + "url": "/api/qiskit/0.46/qiskit.providers.models.PulseDefaults" + }, + { + "title": "QasmBackendConfiguration", + "url": "/api/qiskit/0.46/qiskit.providers.models.QasmBackendConfiguration" + }, + { + "title": "UchannelLO", + "url": "/api/qiskit/0.46/qiskit.providers.models.UchannelLO" + } + ] + } + ] + }, + { + "title": "qiskit.pulse", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/pulse" + }, + { + "title": "Acquire", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.Acquire" + }, + { + "title": "AcquireChannel", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.AcquireChannel" + }, + { + "title": "AlignEquispaced", + "url": "/api/qiskit/0.46/qiskit.pulse.transforms.AlignEquispaced" + }, + { + "title": "AlignFunc", + "url": "/api/qiskit/0.46/qiskit.pulse.transforms.AlignFunc" + }, + { + "title": "AlignLeft", + "url": "/api/qiskit/0.46/qiskit.pulse.transforms.AlignLeft" + }, + { + "title": "AlignRight", + "url": "/api/qiskit/0.46/qiskit.pulse.transforms.AlignRight" + }, + { + "title": "AlignSequential", + "url": "/api/qiskit/0.46/qiskit.pulse.transforms.AlignSequential" + }, + { + "title": "Call", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.Call" + }, + { + "title": "Constant", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Constant_class.rst" + }, + { + "title": "ControlChannel", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.ControlChannel" + }, + { + "title": "Cos", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Cos_class.rst" + }, + { + "title": "Delay", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.Delay" + }, + { + "title": "Drag", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Drag_class.rst" + }, + { + "title": "DriveChannel", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.DriveChannel" + }, + { + "title": "Gaussian", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Gaussian_class.rst" + }, + { + "title": "gaussian_square_echo", + "url": "/api/qiskit/0.46/qiskit.pulse.library.gaussian_square_echo" + }, + { + "title": "GaussianDeriv", + "url": "/api/qiskit/0.46/qiskit.pulse.library.GaussianDeriv" + }, + { + "title": "GaussianSquare", + "url": "/api/qiskit/0.46/qiskit.pulse.library.GaussianSquare" + }, + { + "title": "GaussianSquareDrag", + "url": "/api/qiskit/0.46/qiskit.pulse.library.GaussianSquareDrag" + }, + { + "title": "InstructionScheduleMap", + "url": "/api/qiskit/0.46/qiskit.pulse.InstructionScheduleMap" + }, + { + "title": "MeasureChannel", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.MeasureChannel" + }, + { + "title": "MemorySlot", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.MemorySlot" + }, + { + "title": "ParametricPulse", + "url": "/api/qiskit/0.46/qiskit.pulse.library.ParametricPulse" + }, + { + "title": "Play", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.Play" + }, + { + "title": "Reference", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.Reference" + }, + { + "title": "RegisterSlot", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.RegisterSlot" + }, + { + "title": "RelativeBarrier", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.RelativeBarrier" + }, + { + "title": "Sawtooth", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Sawtooth_class.rst" + }, + { + "title": "Schedule", + "url": "/api/qiskit/0.46/qiskit.pulse.Schedule" + }, + { + "title": "ScheduleBlock", + "url": "/api/qiskit/0.46/qiskit.pulse.ScheduleBlock" + }, + { + "title": "Sech", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Sech_fun.rst" + }, + { + "title": "SechDeriv", + "url": "/api/qiskit/0.46/qiskit.pulse.library.SechDeriv" + }, + { + "title": "SetFrequency", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.SetFrequency" + }, + { + "title": "SetPhase", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.SetPhase" + }, + { + "title": "ShiftFrequency", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.ShiftFrequency" + }, + { + "title": "ShiftPhase", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.ShiftPhase" + }, + { + "title": "Sin", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Sin_class.rst" + }, + { + "title": "Snapshot", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.Snapshot" + }, + { + "title": "SnapshotChannel", + "url": "/api/qiskit/0.46/qiskit.pulse.channels.SnapshotChannel" + }, + { + "title": "Square", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Square_fun.rst" + }, + { + "title": "SymbolicPulse", + "url": "/api/qiskit/0.46/qiskit.pulse.library.SymbolicPulse" + }, + { + "title": "TimeBlockade", + "url": "/api/qiskit/0.46/qiskit.pulse.instructions.TimeBlockade" + }, + { + "title": "Triangle", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Triangle_class.rst" + }, + { + "title": "Waveform", + "url": "/api/qiskit/0.46/qiskit.pulse.library.Waveform" + } + ] + }, + { + "title": "qiskit.qasm", + "url": "/api/qiskit/0.46/qasm" + }, + { + "title": "qiskit.qasm2", + "url": "/api/qiskit/0.46/qasm2" + }, + { + "title": "qiskit.qasm3", + "url": "/api/qiskit/0.46/qasm3" + }, + { + "title": "qiskit.qobj", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/qobj" + }, + { + "title": "GateCalibration", + "url": "/api/qiskit/0.46/qiskit.qobj.GateCalibration" + }, + { + "title": "PulseLibraryItem", + "url": "/api/qiskit/0.46/qiskit.qobj.PulseLibraryItem" + }, + { + "title": "PulseQobj", + "url": "/api/qiskit/0.46/qiskit.qobj.PulseQobj" + }, + { + "title": "PulseQobjConfig", + "url": "/api/qiskit/0.46/qiskit.qobj.PulseQobjConfig" + }, + { + "title": "PulseQobjExperiment", + "url": "/api/qiskit/0.46/qiskit.qobj.PulseQobjExperiment" + }, + { + "title": "PulseQobjExperimentConfig", + "url": "/api/qiskit/0.46/qiskit.qobj.PulseQobjExperimentConfig" + }, + { + "title": "PulseQobjInstruction", + "url": "/api/qiskit/0.46/qiskit.qobj.PulseQobjInstruction" + }, + { + "title": "QasmExperimentCalibrations", + "url": "/api/qiskit/0.46/qiskit.qobj.QasmExperimentCalibrations" + }, + { + "title": "QasmQobj", + "url": "/api/qiskit/0.46/qiskit.qobj.QasmQobj" + }, + { + "title": "QasmQobjConfig", + "url": "/api/qiskit/0.46/qiskit.qobj.QasmQobjConfig" + }, + { + "title": "QasmQobjExperiment", + "url": "/api/qiskit/0.46/qiskit.qobj.QasmQobjExperiment" + }, + { + "title": "QasmQobjExperimentConfig", + "url": "/api/qiskit/0.46/qiskit.qobj.QasmQobjExperimentConfig" + }, + { + "title": "QasmQobjInstruction", + "url": "/api/qiskit/0.46/qiskit.qobj.QasmQobjInstruction" + }, + { + "title": "QobjExperimentHeader", + "url": "/api/qiskit/0.46/qiskit.qobj.QobjExperimentHeader" + }, + { + "title": "QobjHeader", + "url": "/api/qiskit/0.46/qiskit.qobj.QobjHeader" + }, + { + "title": "QobjMeasurementOption", + "url": "/api/qiskit/0.46/qiskit.qobj.QobjMeasurementOption" + } + ] + }, + { + "title": "qiskit.qpy", + "url": "/api/qiskit/0.46/qpy" + }, + { + "title": "qiskit.quantum_info", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/quantum_info" + }, + { + "title": "Chi", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Chi" + }, + { + "title": "Choi", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Choi" + }, + { + "title": "Clifford", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Clifford" + }, + { + "title": "CNOTDihedral", + "url": "/api/qiskit/0.46/qiskit.quantum_info.CNOTDihedral" + }, + { + "title": "DensityMatrix", + "url": "/api/qiskit/0.46/qiskit.quantum_info.DensityMatrix" + }, + { + "title": "Kraus", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Kraus" + }, + { + "title": "Operator", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Operator" + }, + { + "title": "Pauli", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Pauli" + }, + { + "title": "pauli_basis", + "url": "/api/qiskit/0.46/qiskit.quantum_info.pauli_basis" + }, + { + "title": "PauliList", + "url": "/api/qiskit/0.46/qiskit.quantum_info.PauliList" + }, + { + "title": "PTM", + "url": "/api/qiskit/0.46/qiskit.quantum_info.PTM" + }, + { + "title": "Quaternion", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Quaternion" + }, + { + "title": "ScalarOp", + "url": "/api/qiskit/0.46/qiskit.quantum_info.ScalarOp" + }, + { + "title": "SparsePauliOp", + "url": "/api/qiskit/0.46/qiskit.quantum_info.SparsePauliOp" + }, + { + "title": "StabilizerState", + "url": "/api/qiskit/0.46/qiskit.quantum_info.StabilizerState" + }, + { + "title": "Statevector", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Statevector" + }, + { + "title": "Stinespring", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Stinespring" + }, + { + "title": "SuperOp", + "url": "/api/qiskit/0.46/qiskit.quantum_info.SuperOp" + }, + { + "title": "Z2Symmetries", + "url": "/api/qiskit/0.46/qiskit.quantum_info.Z2Symmetries" + } + ] + }, + { + "title": "qiskit.result", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/result" + }, + { + "title": "BaseReadoutMitigator", + "url": "/api/qiskit/0.46/qiskit.result.BaseReadoutMitigator" + }, + { + "title": "CorrelatedReadoutMitigator", + "url": "/api/qiskit/0.46/qiskit.result.CorrelatedReadoutMitigator" + }, + { + "title": "Counts", + "url": "/api/qiskit/0.46/qiskit.result.Counts" + }, + { + "title": "LocalReadoutMitigator", + "url": "/api/qiskit/0.46/qiskit.result.LocalReadoutMitigator" + }, + { + "title": "ProbDistribution", + "url": "/api/qiskit/0.46/qiskit.result.ProbDistribution" + }, + { + "title": "QuasiDistribution", + "url": "/api/qiskit/0.46/qiskit.result.QuasiDistribution" + }, + { + "title": "Result", + "url": "/api/qiskit/0.46/qiskit.result.Result" + }, + { + "title": "ResultError", + "url": "/api/qiskit/0.46/qiskit.result.ResultError" + } + ] + }, + { + "title": "qiskit.scheduler", + "url": "/api/qiskit/0.46/scheduler" + }, + { + "title": "qiskit.synthesis", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/synthesis" + }, + { + "title": "EvolutionSynthesis", + "url": "/api/qiskit/0.46/qiskit.synthesis.EvolutionSynthesis" + }, + { + "title": "LieTrotter", + "url": "/api/qiskit/0.46/qiskit.synthesis.LieTrotter" + }, + { + "title": "MatrixExponential", + "url": "/api/qiskit/0.46/qiskit.synthesis.MatrixExponential" + }, + { + "title": "OneQubitEulerDecomposer", + "url": "/api/qiskit/0.46/qiskit.synthesis.OneQubitEulerDecomposer" + }, + { + "title": "ProductFormula", + "url": "/api/qiskit/0.46/qiskit.synthesis.ProductFormula" + }, + { + "title": "QDrift", + "url": "/api/qiskit/0.46/qiskit.synthesis.QDrift" + }, + { + "title": "SolovayKitaevDecomposition", + "url": "/api/qiskit/0.46/qiskit.synthesis.SolovayKitaevDecomposition" + }, + { + "title": "SuzukiTrotter", + "url": "/api/qiskit/0.46/qiskit.synthesis.SuzukiTrotter" + }, + { + "title": "TwoQubitBasisDecomposer", + "url": "/api/qiskit/0.46/qiskit.synthesis.TwoQubitBasisDecomposer" + }, + { + "title": "XXDecomposer", + "url": "/api/qiskit/0.46/qiskit.synthesis.XXDecomposer" + }, + { + "title": "qiskit.synthesis.unitary.aqc", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/synthesis_aqc" + }, + { + "title": "ApproximateCircuit", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximateCircuit" + }, + { + "title": "ApproximatingObjective", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximatingObjective" + }, + { + "title": "AQC", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.AQC" + }, + { + "title": "CNOTUnitCircuit", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit" + }, + { + "title": "CNOTUnitObjective", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitObjective" + }, + { + "title": "DefaultCNOTUnitObjective", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective" + }, + { + "title": "FastCNOTUnitObjective", + "url": "/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective" + } + ] + } + ] + }, + { + "title": "qiskit.tools", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/tools" + }, + { + "title": "qiskit.tools.jupyter", + "url": "/api/qiskit/0.46/tools_jupyter" + } + ] + }, + { + "title": "qiskit.transpiler", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/transpiler" + }, + { + "title": "AnalysisPass", + "url": "/api/qiskit/0.46/qiskit.transpiler.AnalysisPass" + }, + { + "title": "CouplingMap", + "url": "/api/qiskit/0.46/qiskit.transpiler.CouplingMap" + }, + { + "title": "FencedDAGCircuit", + "url": "/api/qiskit/0.46/qiskit.transpiler.FencedDAGCircuit" + }, + { + "title": "FencedPropertySet", + "url": "/api/qiskit/0.46/qiskit.transpiler.FencedPropertySet" + }, + { + "title": "InstructionDurations", + "url": "/api/qiskit/0.46/qiskit.transpiler.InstructionDurations" + }, + { + "title": "InstructionProperties", + "url": "/api/qiskit/0.46/qiskit.transpiler.InstructionProperties" + }, + { + "title": "Layout", + "url": "/api/qiskit/0.46/qiskit.transpiler.Layout" + }, + { + "title": "PassManager", + "url": "/api/qiskit/0.46/qiskit.transpiler.PassManager" + }, + { + "title": "PassManagerConfig", + "url": "/api/qiskit/0.46/qiskit.transpiler.PassManagerConfig" + }, + { + "title": "StagedPassManager", + "url": "/api/qiskit/0.46/qiskit.transpiler.StagedPassManager" + }, + { + "title": "Target", + "url": "/api/qiskit/0.46/qiskit.transpiler.Target" + }, + { + "title": "TransformationPass", + "url": "/api/qiskit/0.46/qiskit.transpiler.TransformationPass" + }, + { + "title": "TranspileLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.TranspileLayout" + }, + { + "title": "qiskit.transpiler.passes", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/transpiler_passes" + }, + { + "title": "ALAPSchedule", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ALAPSchedule" + }, + { + "title": "ALAPScheduleAnalysis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ALAPScheduleAnalysis" + }, + { + "title": "AlignMeasures", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.AlignMeasures" + }, + { + "title": "ApplyLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ApplyLayout" + }, + { + "title": "AQCSynthesisPlugin", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.AQCSynthesisPlugin" + }, + { + "title": "ASAPSchedule", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ASAPSchedule" + }, + { + "title": "ASAPScheduleAnalysis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ASAPScheduleAnalysis" + }, + { + "title": "BarrierBeforeFinalMeasurements", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements" + }, + { + "title": "BasicSwap", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.BasicSwap" + }, + { + "title": "BasisTranslator", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.BasisTranslator" + }, + { + "title": "CheckGateDirection", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CheckGateDirection" + }, + { + "title": "CheckMap", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CheckMap" + }, + { + "title": "Collect1qRuns", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Collect1qRuns" + }, + { + "title": "Collect2qBlocks", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Collect2qBlocks" + }, + { + "title": "CollectCliffords", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CollectCliffords" + }, + { + "title": "CollectLinearFunctions", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CollectLinearFunctions" + }, + { + "title": "CollectMultiQBlocks", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CollectMultiQBlocks" + }, + { + "title": "CommutationAnalysis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CommutationAnalysis" + }, + { + "title": "CommutativeCancellation", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeCancellation" + }, + { + "title": "CommutativeInverseCancellation", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeInverseCancellation" + }, + { + "title": "Commuting2qGateRouter", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Commuting2qGateRouter" + }, + { + "title": "ConsolidateBlocks", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ConsolidateBlocks" + }, + { + "title": "ConstrainedReschedule", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ConstrainedReschedule" + }, + { + "title": "ContainsInstruction", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ContainsInstruction" + }, + { + "title": "ConvertConditionsToIfOps", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ConvertConditionsToIfOps" + }, + { + "title": "CountOps", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CountOps" + }, + { + "title": "CountOpsLongestPath", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CountOpsLongestPath" + }, + { + "title": "CrosstalkAdaptiveSchedule", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CrosstalkAdaptiveSchedule" + }, + { + "title": "CSPLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CSPLayout" + }, + { + "title": "CXCancellation", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.CXCancellation" + }, + { + "title": "DAGFixedPoint", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.DAGFixedPoint" + }, + { + "title": "DAGLongestPath", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.DAGLongestPath" + }, + { + "title": "Decompose", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Decompose" + }, + { + "title": "DenseLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.DenseLayout" + }, + { + "title": "Depth", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Depth" + }, + { + "title": "DynamicalDecoupling", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.DynamicalDecoupling" + }, + { + "title": "EchoRZXWeylDecomposition", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.EchoRZXWeylDecomposition" + }, + { + "title": "EnlargeWithAncilla", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.EnlargeWithAncilla" + }, + { + "title": "FixedPoint", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.FixedPoint" + }, + { + "title": "FullAncillaAllocation", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.FullAncillaAllocation" + }, + { + "title": "GateDirection", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.GateDirection" + }, + { + "title": "GatesInBasis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.GatesInBasis" + }, + { + "title": "HighLevelSynthesis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.HighLevelSynthesis" + }, + { + "title": "HoareOptimizer", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.HoareOptimizer" + }, + { + "title": "InstructionDurationCheck", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.InstructionDurationCheck" + }, + { + "title": "InverseCancellation", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.InverseCancellation" + }, + { + "title": "Layout2qDistance", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Layout2qDistance" + }, + { + "title": "LinearFunctionsSynthesis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsSynthesis" + }, + { + "title": "LinearFunctionsToPermutations", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsToPermutations" + }, + { + "title": "LookaheadSwap", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.LookaheadSwap" + }, + { + "title": "MergeAdjacentBarriers", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.MergeAdjacentBarriers" + }, + { + "title": "MinimumPoint", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.MinimumPoint" + }, + { + "title": "NoiseAdaptiveLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.NoiseAdaptiveLayout" + }, + { + "title": "NormalizeRXAngle", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.NormalizeRXAngle" + }, + { + "title": "NumTensorFactors", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.NumTensorFactors" + }, + { + "title": "Optimize1qGates", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGates" + }, + { + "title": "Optimize1qGatesDecomposition", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesDecomposition" + }, + { + "title": "Optimize1qGatesSimpleCommutation", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation" + }, + { + "title": "OptimizeCliffords", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.OptimizeCliffords" + }, + { + "title": "PadDelay", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.PadDelay" + }, + { + "title": "PadDynamicalDecoupling", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.PadDynamicalDecoupling" + }, + { + "title": "PulseGates", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.PulseGates" + }, + { + "title": "RemoveBarriers", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RemoveBarriers" + }, + { + "title": "RemoveDiagonalGatesBeforeMeasure", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure" + }, + { + "title": "RemoveFinalMeasurements", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RemoveFinalMeasurements" + }, + { + "title": "RemoveResetInZeroState", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RemoveResetInZeroState" + }, + { + "title": "ResetAfterMeasureSimplification", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ResetAfterMeasureSimplification" + }, + { + "title": "RXCalibrationBuilder", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RXCalibrationBuilder" + }, + { + "title": "RZXCalibrationBuilder", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilder" + }, + { + "title": "RZXCalibrationBuilderNoEcho", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho" + }, + { + "title": "SabreLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SabreLayout" + }, + { + "title": "SabrePreLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SabrePreLayout" + }, + { + "title": "SabreSwap", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SabreSwap" + }, + { + "title": "SetIOLatency", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SetIOLatency" + }, + { + "title": "SetLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SetLayout" + }, + { + "title": "Size", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Size" + }, + { + "title": "SolovayKitaev", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaev" + }, + { + "title": "SolovayKitaevSynthesis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaevSynthesis" + }, + { + "title": "StochasticSwap", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.StochasticSwap" + }, + { + "title": "TemplateOptimization", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.TemplateOptimization" + }, + { + "title": "TimeUnitConversion", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.TimeUnitConversion" + }, + { + "title": "TranslateParameterizedGates", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.TranslateParameterizedGates" + }, + { + "title": "TrivialLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.TrivialLayout" + }, + { + "title": "UnitarySynthesis", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.UnitarySynthesis" + }, + { + "title": "Unroll3qOrMore", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Unroll3qOrMore" + }, + { + "title": "UnrollCustomDefinitions", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.UnrollCustomDefinitions" + }, + { + "title": "Unroller", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Unroller" + }, + { + "title": "UnrollForLoops", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.UnrollForLoops" + }, + { + "title": "ValidatePulseGates", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.ValidatePulseGates" + }, + { + "title": "VF2Layout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.VF2Layout" + }, + { + "title": "VF2PostLayout", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.VF2PostLayout" + }, + { + "title": "Width", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.Width" + }, + { + "title": "qiskit.transpiler.passes.synthesis.plugin", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/transpiler_synthesis_plugins" + }, + { + "title": "HighLevelSynthesisPlugin", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin" + }, + { + "title": "HighLevelSynthesisPluginManager", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager" + }, + { + "title": "unitary_synthesis_plugin_names", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names" + }, + { + "title": "UnitarySynthesisPlugin", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin" + }, + { + "title": "UnitarySynthesisPluginManager", + "url": "/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager" + } + ] + } + ] + }, + { + "title": "qiskit.transpiler.preset_passmanagers", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/transpiler_preset" + }, + { + "title": "qiskit.transpiler.preset_passmanagers.plugin", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/transpiler_plugins" + }, + { + "title": "PassManagerStagePlugin", + "url": "/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin" + }, + { + "title": "PassManagerStagePluginManager", + "url": "/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager" + } + ] + } + ] + } + ] + }, + { + "title": "qiskit.utils", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/utils" + }, + { + "title": "QuantumInstance", + "url": "/api/qiskit/0.46/qiskit.utils.QuantumInstance" + }, + { + "title": "qiskit.utils.mitigation", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/utils_mitigation" + }, + { + "title": "CompleteMeasFitter", + "url": "/api/qiskit/0.46/qiskit.utils.mitigation.CompleteMeasFitter" + }, + { + "title": "TensoredMeasFitter", + "url": "/api/qiskit/0.46/qiskit.utils.mitigation.TensoredMeasFitter" + } + ] + } + ] + }, + { + "title": "qiskit.visualization", + "children": [ + { + "title": "Overview", + "url": "/api/qiskit/0.46/visualization" + }, + { + "title": "array_to_latex", + "url": "/api/qiskit/0.46/qiskit.visualization.array_to_latex" + }, + { + "title": "circuit_drawer", + "url": "/api/qiskit/0.46/qiskit.visualization.circuit_drawer" + }, + { + "title": "dag_drawer", + "url": "/api/qiskit/0.46/qiskit.visualization.dag_drawer" + }, + { + "title": "DefaultStyle", + "url": "/api/qiskit/0.46/qiskit.visualization.circuit.qcstyle.DefaultStyle" + }, + { + "title": "IQXDebugging", + "url": "/api/qiskit/0.46/qiskit.visualization.pulse.IQXDebugging" + }, + { + "title": "IQXSimple", + "url": "/api/qiskit/0.46/qiskit.visualization.pulse.IQXSimple" + }, + { + "title": "IQXStandard", + "url": "/api/qiskit/0.46/qiskit.visualization.pulse.IQXStandard" + }, + { + "title": "pass_manager_drawer", + "url": "/api/qiskit/0.46/qiskit.visualization.pass_manager_drawer" + }, + { + "title": "plot_bloch_multivector", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_bloch_multivector" + }, + { + "title": "plot_bloch_vector", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_bloch_vector" + }, + { + "title": "plot_circuit_layout", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_circuit_layout" + }, + { + "title": "plot_coupling_map", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_coupling_map" + }, + { + "title": "plot_distribution", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_distribution" + }, + { + "title": "plot_error_map", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_error_map" + }, + { + "title": "plot_gate_map", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_gate_map" + }, + { + "title": "plot_histogram", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_histogram" + }, + { + "title": "plot_state_city", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_state_city" + }, + { + "title": "plot_state_hinton", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_state_hinton" + }, + { + "title": "plot_state_paulivec", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_state_paulivec" + }, + { + "title": "plot_state_qsphere", + "url": "/api/qiskit/0.46/qiskit.visualization.plot_state_qsphere" + }, + { + "title": "pulse_drawer", + "url": "/api/qiskit/0.46/qiskit.visualization.pulse_drawer" + }, + { + "title": "timeline_drawer", + "url": "/api/qiskit/0.46/qiskit.visualization.timeline_drawer" + }, + { + "title": "visualize_transition", + "url": "/api/qiskit/0.46/qiskit.visualization.visualize_transition" + } + ] + }, + { + "title": "Release notes", + "children": [ + { + "title": "0.46", + "url": "/api/qiskit/release-notes/0.46" + }, + { + "title": "0.45", + "url": "/api/qiskit/release-notes/0.45" + }, + { + "title": "0.44", + "url": "/api/qiskit/release-notes/0.44" + }, + { + "title": "0.43", + "url": "/api/qiskit/release-notes/0.43" + }, + { + "title": "0.42", + "url": "/api/qiskit/release-notes/0.42" + }, + { + "title": "0.41", + "url": "/api/qiskit/release-notes/0.41" + }, + { + "title": "0.40", + "url": "/api/qiskit/release-notes/0.40" + }, + { + "title": "0.39", + "url": "/api/qiskit/release-notes/0.39" + }, + { + "title": "0.38", + "url": "/api/qiskit/release-notes/0.38" + }, + { + "title": "0.37", + "url": "/api/qiskit/release-notes/0.37" + }, + { + "title": "0.36", + "url": "/api/qiskit/release-notes/0.36" + }, + { + "title": "0.35", + "url": "/api/qiskit/release-notes/0.35" + }, + { + "title": "0.34", + "url": "/api/qiskit/release-notes/0.34" + }, + { + "title": "0.33", + "url": "/api/qiskit/release-notes/0.33" + }, + { + "title": "0.32", + "url": "/api/qiskit/release-notes/0.32" + }, + { + "title": "0.31", + "url": "/api/qiskit/release-notes/0.31" + }, + { + "title": "0.30", + "url": "/api/qiskit/release-notes/0.30" + }, + { + "title": "0.29", + "url": "/api/qiskit/release-notes/0.29" + }, + { + "title": "0.28", + "url": "/api/qiskit/release-notes/0.28" + }, + { + "title": "0.27", + "url": "/api/qiskit/release-notes/0.27" + }, + { + "title": "0.26", + "url": "/api/qiskit/release-notes/0.26" + }, + { + "title": "0.25", + "url": "/api/qiskit/release-notes/0.25" + }, + { + "title": "0.24", + "url": "/api/qiskit/release-notes/0.24" + }, + { + "title": "0.23", + "url": "/api/qiskit/release-notes/0.23" + }, + { + "title": "0.22", + "url": "/api/qiskit/release-notes/0.22" + }, + { + "title": "0.21", + "url": "/api/qiskit/release-notes/0.21" + }, + { + "title": "0.20", + "url": "/api/qiskit/release-notes/0.20" + }, + { + "title": "0.19", + "url": "/api/qiskit/release-notes/0.19" + }, + { + "title": "0.18", + "url": "/api/qiskit/release-notes/0.18" + }, + { + "title": "0.17", + "url": "/api/qiskit/release-notes/0.17" + }, + { + "title": "0.16", + "url": "/api/qiskit/release-notes/0.16" + }, + { + "title": "0.15", + "url": "/api/qiskit/release-notes/0.15" + }, + { + "title": "0.14", + "url": "/api/qiskit/release-notes/0.14" + }, + { + "title": "0.13", + "url": "/api/qiskit/release-notes/0.13" + }, + { + "title": "0.12", + "url": "/api/qiskit/release-notes/0.12" + }, + { + "title": "0.11", + "url": "/api/qiskit/release-notes/0.11" + }, + { + "title": "0.10", + "url": "/api/qiskit/release-notes/0.10" + }, + { + "title": "0.9", + "url": "/api/qiskit/release-notes/0.9" + }, + { + "title": "0.8", + "url": "/api/qiskit/release-notes/0.8" + }, + { + "title": "0.7", + "url": "/api/qiskit/release-notes/0.7" + }, + { + "title": "0.6", + "url": "/api/qiskit/release-notes/0.6" + }, + { + "title": "0.5", + "url": "/api/qiskit/release-notes/0.5" + } + ] + } + ], + "collapsed": true +} + diff --git a/docs/api/qiskit/0.46/algorithms.md b/docs/api/qiskit/0.46/algorithms.md new file mode 100644 index 00000000000..069d9bd0d13 --- /dev/null +++ b/docs/api/qiskit/0.46/algorithms.md @@ -0,0 +1,279 @@ +--- +title: algorithms +description: API reference for qiskit.algorithms +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms +--- + + + + + + + +# Algorithms + + + +`qiskit.algorithms` + + + The [`qiskit.algorithms`](#module-qiskit.algorithms "qiskit.algorithms") module has been migrated to an independent package: [https://github.com/qiskit-community/qiskit-algorithms](https://github.com/qiskit-community/qiskit-algorithms). The current import path is deprecated and will be removed no earlier than 3 months after the release date. If your code uses primitives, you can run `pip install qiskit_algorithms` and import `from qiskit_algorithms` instead. If you use opflow/quantum instance-based algorithms, please update your code to use primitives following: [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) before migrating to the new package. + + +It contains a collection of quantum algorithms, for use with quantum computers, to carry out research and investigate how to solve problems in different domains on near-term quantum devices with short depth circuits. + +Algorithms configuration includes the use of [`optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers") which were designed to be swappable sub-parts of an algorithm. Any component and may be exchanged for a different implementation of the same component type in order to potentially alter the behavior and outcome of the algorithm. + +Quantum algorithms are run via a `QuantumInstance` which must be set with the desired backend where the algorithm’s circuits will be executed and be configured with a number of compile and runtime parameters controlling circuit compilation and execution. It ultimately uses [Terra](https://www.qiskit.org/terra) for the actual compilation and execution of the quantum circuits created by the algorithm and its components. + +## Algorithms + +It contains a variety of quantum algorithms and these have been grouped by logical function such as minimum eigensolvers and amplitude amplifiers. + +### Amplitude Amplifiers + +| | | +| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| [`AmplificationProblem`](qiskit.algorithms.AmplificationProblem "qiskit.algorithms.AmplificationProblem") | The amplification problem is the input to amplitude amplification algorithms, like Grover. | +| [`AmplitudeAmplifier`](qiskit.algorithms.AmplitudeAmplifier "qiskit.algorithms.AmplitudeAmplifier") | The interface for amplification algorithms. | +| [`Grover`](qiskit.algorithms.Grover "qiskit.algorithms.Grover") | Grover's Search algorithm. | +| [`GroverResult`](qiskit.algorithms.GroverResult "qiskit.algorithms.GroverResult") | Grover Result. | + +### Amplitude Estimators + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| [`AmplitudeEstimator`](qiskit.algorithms.AmplitudeEstimator "qiskit.algorithms.AmplitudeEstimator") | The Amplitude Estimation interface. | +| [`AmplitudeEstimatorResult`](qiskit.algorithms.AmplitudeEstimatorResult "qiskit.algorithms.AmplitudeEstimatorResult") | The results object for amplitude estimation algorithms. | +| [`AmplitudeEstimation`](qiskit.algorithms.AmplitudeEstimation "qiskit.algorithms.AmplitudeEstimation") | The Quantum Phase Estimation-based Amplitude Estimation algorithm. | +| [`AmplitudeEstimationResult`](qiskit.algorithms.AmplitudeEstimationResult "qiskit.algorithms.AmplitudeEstimationResult") | The `AmplitudeEstimation` result object. | +| [`EstimationProblem`](qiskit.algorithms.EstimationProblem "qiskit.algorithms.EstimationProblem") | The estimation problem is the input to amplitude estimation algorithm. | +| [`FasterAmplitudeEstimation`](qiskit.algorithms.FasterAmplitudeEstimation "qiskit.algorithms.FasterAmplitudeEstimation") | The Faster Amplitude Estimation algorithm. | +| [`FasterAmplitudeEstimationResult`](qiskit.algorithms.FasterAmplitudeEstimationResult "qiskit.algorithms.FasterAmplitudeEstimationResult") | The result object for the Faster Amplitude Estimation algorithm. | +| [`IterativeAmplitudeEstimation`](qiskit.algorithms.IterativeAmplitudeEstimation "qiskit.algorithms.IterativeAmplitudeEstimation") | The Iterative Amplitude Estimation algorithm. | +| [`IterativeAmplitudeEstimationResult`](qiskit.algorithms.IterativeAmplitudeEstimationResult "qiskit.algorithms.IterativeAmplitudeEstimationResult") | The `IterativeAmplitudeEstimation` result object. | +| [`MaximumLikelihoodAmplitudeEstimation`](qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation "qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation") | The Maximum Likelihood Amplitude Estimation algorithm. | +| [`MaximumLikelihoodAmplitudeEstimationResult`](qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult "qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult") | The `MaximumLikelihoodAmplitudeEstimation` result object. | + +### Eigensolvers + +Algorithms to find eigenvalues of an operator. For chemistry these can be used to find excited states of a molecule, and `qiskit-nature` has some algorithms that leverage chemistry specific knowledge to do this in that application domain. + +#### Primitive-based Eigensolvers + +These algorithms are based on the Qiskit Primitives, a new execution paradigm that replaces the use of [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") in algorithms. To ensure continued support and development, we recommend using the primitive-based Eigensolvers in place of the legacy [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance")-based ones. + +| | | +| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| [`eigensolvers`](qiskit.algorithms.eigensolvers#module-qiskit.algorithms.eigensolvers "qiskit.algorithms.eigensolvers") | Eigensolvers Package (qiskit.algorithms.eigensolvers) | + +#### Legacy Eigensolvers + +These algorithms, still based on the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance"), are superseded by the primitive-based versions in the section above but are still supported for now. + +| | | +| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | +| [`Eigensolver`](qiskit.algorithms.Eigensolver "qiskit.algorithms.Eigensolver") | Deprecated: Eigensolver Interface. | +| [`EigensolverResult`](qiskit.algorithms.EigensolverResult "qiskit.algorithms.EigensolverResult") | Deprecated: Eigensolver Result. | +| [`NumPyEigensolver`](qiskit.algorithms.NumPyEigensolver "qiskit.algorithms.NumPyEigensolver") | Deprecated: NumPy Eigensolver algorithm. | +| [`VQD`](qiskit.algorithms.VQD "qiskit.algorithms.VQD") | Deprecated: Variational Quantum Deflation algorithm. | +| [`VQDResult`](qiskit.algorithms.VQDResult "qiskit.algorithms.VQDResult") | Deprecated: VQD Result. | + +### Time Evolvers + +Algorithms to evolve quantum states in time. Both real and imaginary time evolution is possible with algorithms that support them. For machine learning, Quantum Imaginary Time Evolution might be used to train Quantum Boltzmann Machine Neural Networks for example. + +#### Primitive-based Time Evolvers + +These algorithms are based on the Qiskit Primitives, a new execution paradigm that replaces the use of [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") in algorithms. To ensure continued support and development, we recommend using the primitive-based Time Evolvers in place of the legacy [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance")-based ones. + +| | | +| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | +| [`RealTimeEvolver`](qiskit.algorithms.RealTimeEvolver "qiskit.algorithms.RealTimeEvolver") | Interface for Quantum Real Time Evolution. | +| [`ImaginaryTimeEvolver`](qiskit.algorithms.ImaginaryTimeEvolver "qiskit.algorithms.ImaginaryTimeEvolver") | Interface for Quantum Imaginary Time Evolution. | +| [`TimeEvolutionResult`](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.TimeEvolutionResult") | Class for holding time evolution result. | +| [`TimeEvolutionProblem`](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.TimeEvolutionProblem") | Time evolution problem class. | +| [`PVQD`](qiskit.algorithms.PVQD "qiskit.algorithms.PVQD") | The projected Variational Quantum Dynamics (p-VQD) Algorithm. | +| [`PVQDResult`](qiskit.algorithms.PVQDResult "qiskit.algorithms.PVQDResult") | The result object for the p-VQD algorithm. | +| [`SciPyImaginaryEvolver`](qiskit.algorithms.SciPyImaginaryEvolver "qiskit.algorithms.SciPyImaginaryEvolver") | Classical Evolver for imaginary time evolution. | +| [`SciPyRealEvolver`](qiskit.algorithms.SciPyRealEvolver "qiskit.algorithms.SciPyRealEvolver") | Classical Evolver for real time evolution. | +| [`VarQITE`](qiskit.algorithms.VarQITE "qiskit.algorithms.VarQITE") | Variational Quantum Imaginary Time Evolution algorithm. | +| [`VarQRTE`](qiskit.algorithms.VarQRTE "qiskit.algorithms.VarQRTE") | Variational Quantum Real Time Evolution algorithm. | + +#### Legacy Time Evolvers + +These algorithms, still based on the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance"), are superseded by the primitive-based versions in the section above but are still supported for now. + +| | | +| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| [`RealEvolver`](qiskit.algorithms.RealEvolver "qiskit.algorithms.RealEvolver") | Deprecated: Interface for Quantum Real Time Evolution. | +| [`ImaginaryEvolver`](qiskit.algorithms.ImaginaryEvolver "qiskit.algorithms.ImaginaryEvolver") | Deprecated: Interface for Quantum Imaginary Time Evolution. | +| [`TrotterQRTE`](qiskit.algorithms.TrotterQRTE "qiskit.algorithms.TrotterQRTE") | Deprecated: Quantum Real Time Evolution using Trotterization. | +| [`EvolutionResult`](qiskit.algorithms.EvolutionResult "qiskit.algorithms.EvolutionResult") | Deprecated: Class for holding evolution result. | +| [`EvolutionProblem`](qiskit.algorithms.EvolutionProblem "qiskit.algorithms.EvolutionProblem") | Deprecated: Evolution problem class. | + +#### Variational Quantum Time Evolution + +Classes used by variational quantum time evolution algorithms - [`VarQITE`](qiskit.algorithms.VarQITE "qiskit.algorithms.VarQITE") and [`VarQRTE`](qiskit.algorithms.VarQRTE "qiskit.algorithms.VarQRTE"). + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| [`time_evolvers.variational`](qiskit.algorithms.time_evolvers.variational#module-qiskit.algorithms.time_evolvers.variational "qiskit.algorithms.time_evolvers.variational") | Variational Quantum Time Evolutions (qiskit.algorithms.time\_evolvers.variational) | + +#### Trotterization-based Quantum Real Time Evolution + +Package for primitives-enabled Trotterization-based quantum time evolution algorithm - `TrotterQRTE`. + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| [`time_evolvers.trotterization`](qiskit.algorithms.time_evolvers.trotterization#module-qiskit.algorithms.time_evolvers.trotterization "qiskit.algorithms.time_evolvers.trotterization") | This package contains Trotterization-based Quantum Real Time Evolution algorithm. | + +### Gradients + +Algorithms to calculate the gradient of a quantum circuit. + +| | | +| ----------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| [`gradients`](qiskit.algorithms.gradients#module-qiskit.algorithms.gradients "qiskit.algorithms.gradients") | Gradients (qiskit.algorithms.gradients) | + +### Minimum Eigensolvers + +Algorithms that can find the minimum eigenvalue of an operator. + +#### Primitive-based Minimum Eigensolvers + +These algorithms are based on the Qiskit Primitives, a new execution paradigm that replaces the use of [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") in algorithms. To ensure continued support and development, we recommend using the primitive-based Minimum Eigensolvers in place of the legacy [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance")-based ones. + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| [`minimum_eigensolvers`](qiskit.algorithms.minimum_eigensolvers#module-qiskit.algorithms.minimum_eigensolvers "qiskit.algorithms.minimum_eigensolvers") | Minimum Eigensolvers Package (qiskit.algorithms.minimum\_eigensolvers) | + +#### Legacy Minimum Eigensolvers + +These algorithms, still based on the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance"), are superseded by the primitive-based versions in the section above but are still supported for now. + +| | | +| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| [`MinimumEigensolver`](qiskit.algorithms.MinimumEigensolver "qiskit.algorithms.MinimumEigensolver") | Deprecated: Minimum Eigensolver Interface. | +| [`MinimumEigensolverResult`](qiskit.algorithms.MinimumEigensolverResult "qiskit.algorithms.MinimumEigensolverResult") | Deprecated: Minimum Eigensolver Result. | +| [`NumPyMinimumEigensolver`](qiskit.algorithms.NumPyMinimumEigensolver "qiskit.algorithms.NumPyMinimumEigensolver") | Deprecated: Numpy Minimum Eigensolver algorithm. | +| [`QAOA`](qiskit.algorithms.QAOA "qiskit.algorithms.QAOA") | Deprecated: Quantum Approximate Optimization Algorithm. | +| [`VQE`](qiskit.algorithms.VQE "qiskit.algorithms.VQE") | Deprecated: Variational Quantum Eigensolver algorithm. | + +### Optimizers + +Classical optimizers for use by quantum variational algorithms. + +| | | +| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers") | Optimizers (qiskit.algorithms.optimizers) It contains a variety of classical optimizers for use by quantum variational algorithms, such as VQE. Logically, these optimizers can be divided into two categories: | + +### Phase Estimators + +Algorithms that estimate the phases of eigenstates of a unitary. + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`HamiltonianPhaseEstimation`](qiskit.algorithms.HamiltonianPhaseEstimation "qiskit.algorithms.HamiltonianPhaseEstimation") | Run the Quantum Phase Estimation algorithm to find the eigenvalues of a Hermitian operator. | +| [`HamiltonianPhaseEstimationResult`](qiskit.algorithms.HamiltonianPhaseEstimationResult "qiskit.algorithms.HamiltonianPhaseEstimationResult") | Store and manipulate results from running HamiltonianPhaseEstimation. | +| [`PhaseEstimationScale`](qiskit.algorithms.PhaseEstimationScale "qiskit.algorithms.PhaseEstimationScale") | Set and use a bound on eigenvalues of a Hermitian operator in order to ensure phases are in the desired range and to convert measured phases into eigenvectors. | +| [`PhaseEstimation`](qiskit.algorithms.PhaseEstimation "qiskit.algorithms.PhaseEstimation") | Run the Quantum Phase Estimation (QPE) algorithm. | +| [`PhaseEstimationResult`](qiskit.algorithms.PhaseEstimationResult "qiskit.algorithms.PhaseEstimationResult") | Store and manipulate results from running PhaseEstimation. | +| [`IterativePhaseEstimation`](qiskit.algorithms.IterativePhaseEstimation "qiskit.algorithms.IterativePhaseEstimation") | Run the Iterative quantum phase estimation (QPE) algorithm. | + +### State Fidelities + +Algorithms that compute the fidelity of pairs of quantum states. + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| [`state_fidelities`](qiskit.algorithms.state_fidelities#module-qiskit.algorithms.state_fidelities "qiskit.algorithms.state_fidelities") | State Fidelity Interfaces (qiskit.algorithms.state\_fidelities) | + +### Exceptions + +### AlgorithmError + + + +`qiskit.algorithms.AlgorithmError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/exceptions.py "view source code") + +For Algorithm specific errors. + +Set the error message. + +### Utility classes + +Utility classes used by algorithms (mainly for type-hinting purposes). + +| | | +| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| [`AlgorithmJob`](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob")(function, \*args, \*\*kwargs) | This empty class is introduced for typing purposes. | + +### Utility functions + +Utility functions used by algorithms. + +### eval\_observables + + + +`qiskit.algorithms.eval_observables(quantum_instance, quantum_state, observables, expectation, threshold=1e-12)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/aux_ops_evaluator.py "view source code") + +Deprecated: Accepts a list or a dictionary of operators and calculates their expectation values - means and standard deviations. They are calculated with respect to a quantum state provided. A user can optionally provide a threshold value which filters mean values falling below the threshold. + +This function has been superseded by the `qiskit.algorithms.observables_evaluator.eval_observables()` function. It will be deprecated in a future release and subsequently removed after that. + + + The function `qiskit.algorithms.aux_ops_evaluator.eval_observables()` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the function `qiskit.algorithms.observables_evaluator.estimate_observables`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – A quantum instance used for calculations. +* **quantum\_state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – An unparametrized quantum circuit representing a quantum state that expectation values are computed against. +* **observables** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*]*) – A list or a dictionary of operators whose expectation values are to be calculated. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")) – An instance of ExpectationBase which defines a method for calculating expectation values. +* **threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – A threshold value that defines which mean values should be neglected (helpful for ignoring numerical instabilities close to 0). + +**Returns** + +A list or a dictionary of tuples (mean, standard deviation). + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If a `quantum_state` with free parameters is provided. + +**Return type** + +ListOrDict\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)"), [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")]] + +### estimate\_observables + + + +`qiskit.algorithms.estimate_observables(estimator, quantum_state, observables, parameter_values=None, threshold=1e-12)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/observables_evaluator.py "view source code") + +Accepts a sequence of operators and calculates their expectation values - means and metadata. They are calculated with respect to a quantum state provided. A user can optionally provide a threshold value which filters mean values falling below the threshold. + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – An estimator primitive used for calculations. +* **quantum\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A (parameterized) quantum circuit preparing a quantum state that expectation values are computed against. +* **observables** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – A list or a dictionary of operators whose expectation values are to be calculated. +* **parameter\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Optional list of parameters values to evaluate the quantum circuit on. +* **threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – A threshold value that defines which mean values should be neglected (helpful for ignoring numerical instabilities close to 0). + +**Returns** + +A list or a dictionary of tuples (mean, metadata). + +**Raises** + +[**AlgorithmError**](#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If a primitive job is not successful. + +**Return type** + +ListOrDict\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)"), [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), Any]]] + diff --git a/docs/api/qiskit/0.46/assembler.md b/docs/api/qiskit/0.46/assembler.md new file mode 100644 index 00000000000..e41da15b1d5 --- /dev/null +++ b/docs/api/qiskit/0.46/assembler.md @@ -0,0 +1,186 @@ +--- +title: assembler +description: API reference for qiskit.assembler +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.assembler +--- + + + + + + + +# Circuit and Schedule Assembler + + + +`qiskit.assembler` + +## Circuit Assembler + +### assemble\_circuits + + + +`qiskit.assembler.assemble_circuits(circuits, run_config, qobj_id, qobj_header)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/assembler/assemble_circuits.py "view source code") + +Assembles a list of circuits into a qobj that can be run on the backend. + +**Parameters** + +* **circuits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*]*) – circuit(s) to assemble +* **run\_config** ([*RunConfig*](qiskit.assembler.RunConfig "qiskit.assembler.run_config.RunConfig")) – configuration of the runtime environment +* **qobj\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – identifier for the generated qobj +* **qobj\_header** ([*QobjHeader*](qiskit.qobj.QobjHeader "qiskit.qobj.common.QobjHeader")) – header to pass to the results + +**Returns** + +The qobj to be run on the backends + +**Return type** + +[*QasmQobj*](qiskit.qobj.QasmQobj "qiskit.qobj.qasm_qobj.QasmQobj") + +**Examples** + +```python +from qiskit.circuit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.assembler import assemble_circuits +from qiskit.assembler.run_config import RunConfig +# Build a circuit to convert into a Qobj +q = QuantumRegister(2) +c = ClassicalRegister(2) +qc = QuantumCircuit(q, c) +qc.h(q[0]) +qc.cx(q[0], q[1]) +qc.measure(q, c) +# Assemble a Qobj from the input circuit +qobj = assemble_circuits(circuits=[qc], + qobj_id="custom-id", + qobj_header=[], + run_config=RunConfig(shots=2000, memory=True, init_qubits=True)) +``` + +## Schedule Assembler + +### assemble\_schedules + + + +`qiskit.assembler.assemble_schedules(schedules, qobj_id, qobj_header, run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/assembler/assemble_schedules.py "view source code") + +Assembles a list of schedules into a qobj that can be run on the backend. + +**Parameters** + +* **schedules** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") *|*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")*]]*) – Schedules to assemble. +* **qobj\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Identifier for the generated qobj. +* **qobj\_header** ([*QobjHeader*](qiskit.qobj.QobjHeader "qiskit.qobj.common.QobjHeader")) – Header to pass to the results. +* **run\_config** ([*RunConfig*](qiskit.assembler.RunConfig "qiskit.assembler.run_config.RunConfig")) – Configuration of the runtime environment. + +**Returns** + +The Qobj to be run on the backends. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – when frequency settings are not supplied. + +**Return type** + +[*PulseQobj*](qiskit.qobj.PulseQobj "qiskit.qobj.pulse_qobj.PulseQobj") + +**Examples** + +```python +from qiskit import pulse +from qiskit.assembler import assemble_schedules +from qiskit.assembler.run_config import RunConfig +# Construct a Qobj header for the output Qobj +header = {"backend_name": "FakeOpenPulse2Q", "backend_version": "0.0.0"} +# Build a configuration object for the output Qobj +config = RunConfig(shots=1024, + memory=False, + meas_level=1, + meas_return='avg', + memory_slot_size=100, + parametric_pulses=[], + init_qubits=True, + qubit_lo_freq=[4900000000.0, 5000000000.0], + meas_lo_freq=[6500000000.0, 6600000000.0], + schedule_los=[]) +# Build a Pulse schedule to assemble into a Qobj +schedule = pulse.Schedule() +schedule += pulse.Play(pulse.Waveform([0.1] * 16, name="test0"), + pulse.DriveChannel(0), + name="test1") +schedule += pulse.Play(pulse.Waveform([0.1] * 16, name="test1"), + pulse.DriveChannel(0), + name="test2") +schedule += pulse.Play(pulse.Waveform([0.5] * 16, name="test0"), + pulse.DriveChannel(0), + name="test1") +# Assemble a Qobj from the schedule. +pulseQobj = assemble_schedules(schedules=[schedule], + qobj_id="custom-id", + qobj_header=header, + run_config=config) +``` + +## Disassembler + +### disassemble + + + +`qiskit.assembler.disassemble(qobj)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/assembler/disassemble.py "view source code") + +Disassemble a qobj and return the circuits or pulse schedules, run\_config, and user header. + + + `disassemble(assemble(qc))` is not guaranteed to produce an exactly equal circuit to the input, due to limitations in the [`QasmQobj`](qiskit.qobj.QasmQobj "qiskit.qobj.QasmQobj") format that need to be maintained for backend system compatibility. This is most likely to be the case when using newer features of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). In most cases, the output should be equivalent, if not quite equal. + + +**Parameters** + +**qobj** (*Qobj*) – The input qobj object to disassemble + +**Returns** + +The disassembled program which consists of: + +> * programs: A list of quantum circuits or pulse schedules +> * run\_config: The dict of the run config +> * user\_qobj\_header: The dict of any user headers in the qobj + +**Return type** + +Union\[CircuitModule, PulseModule] + +**Examples** + +```python +from qiskit.circuit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.compiler.assembler import assemble +from qiskit.assembler.disassemble import disassemble +# Create a circuit to assemble into a qobj +q = QuantumRegister(2) +c = ClassicalRegister(2) +qc = QuantumCircuit(q, c) +qc.h(q[0]) +qc.cx(q[0], q[1]) +qc.measure(q, c) +# Assemble the circuit into a Qobj +qobj = assemble(qc, shots=2000, memory=True) +# Disassemble the qobj back into a circuit +circuits, run_config_out, headers = disassemble(qobj) +``` + +## RunConfig + +| | | +| -------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| [`RunConfig`](qiskit.assembler.RunConfig "qiskit.assembler.RunConfig")(\[shots, seed\_simulator, memory, ...]) | Class for Run Configuration. | + diff --git a/docs/api/qiskit/0.46/circuit.md b/docs/api/qiskit/0.46/circuit.md new file mode 100644 index 00000000000..0f3a54be0dd --- /dev/null +++ b/docs/api/qiskit/0.46/circuit.md @@ -0,0 +1,357 @@ +--- +title: circuit +description: API reference for qiskit.circuit +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.circuit +--- + + + + + + + +# Quantum Circuits + + + +`qiskit.circuit` + +## Overview + +The fundamental element of quantum computing is the **quantum circuit**. A quantum circuit is a computational routine consisting of coherent quantum operations on quantum data, such as qubits. It is an ordered sequence of quantum gates, measurements and resets, which may be conditioned on real-time classical computation. A set of quantum gates is said to be universal if any unitary transformation of the quantum data can be efficiently approximated arbitrarily well as a sequence of gates in the set. Any quantum program can be represented by a sequence of quantum circuits and classical near-time computation. + +In Qiskit, this core element is represented by the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") class. Below is an example of a quantum circuit that makes a three-qubit GHZ state defined as: + +$$ +|\psi\rangle = \left(|000\rangle+|111\rangle\right)/\sqrt{2} +$$ + +```python +from qiskit import QuantumCircuit +# Create a circuit with a register of three qubits +circ = QuantumCircuit(3) +# H gate on qubit 0, putting this qubit in a superposition of |0> + |1>. +circ.h(0) +# A CX (CNOT) gate on control qubit 0 and target qubit 1 generating a Bell state. +circ.cx(0, 1) +# CX (CNOT) gate on control qubit 0 and target qubit 2 resulting in a GHZ state. +circ.cx(0, 2) +# Draw the circuit +circ.draw('mpl') +``` + +![../\_images/circuit-1.png](/images/api/qiskit/0.46/circuit-1.png) + +## Supplementary Information + +### Quantum Circuit with conditionals + +When building a quantum circuit, there can be interest in applying a certain gate only if a classical register has a specific value. This can be done with the [`InstructionSet.c_if()`](qiskit.circuit.InstructionSet#c_if "qiskit.circuit.InstructionSet.c_if") method. + +In the following example, we start with a single-qubit circuit formed by only a Hadamard gate ([`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate")), in which we expect to get $|0\rangle$ and $|1\rangle$ with equal probability. + +```python +from qiskit import transpile, QuantumRegister, ClassicalRegister, QuantumCircuit +qr = QuantumRegister(1) +cr = ClassicalRegister(1) +qc = QuantumCircuit(qr, cr) +qc.h(0) +qc.measure(0, 0) +qc.draw('mpl') +``` + +![../\_images/circuit-2.png](/images/api/qiskit/0.46/circuit-2.png) + +```python +from qiskit.providers.basic_provider import BasicSimulator +backend = BasicSimulator() +tqc = transpile(qc, backend) +counts = backend.run(tqc).result().get_counts() + +print(counts) +``` + +```python +{'0': 524, '1': 500} +``` + +Now, we add an [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") only if the value of the [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") is 0. That way, if the state is $|0\rangle$, it will be changed to $|1\rangle$ and if the state is $|1\rangle$, it will not be changed at all, so the final state will always be $|1\rangle$. + +```python +from qiskit import transpile, QuantumRegister, ClassicalRegister, QuantumCircuit + +qr = QuantumRegister(1) +cr = ClassicalRegister(1) +qc = QuantumCircuit(qr, cr) +qc.h(0) +qc.measure(0, 0) + +qc.x(0).c_if(cr, 0) +qc.measure(0, 0) + +qc.draw('mpl') +``` + +![../\_images/circuit-3.png](/images/api/qiskit/0.46/circuit-3.png) + +```python +from qiskit.providers.basic_provider import BasicSimulator +backend = BasicSimulator() +tqc = transpile(qc, backend) +counts = backend.run(tqc).result().get_counts() + +print(counts) +``` + +```python +{'1': 1024} +``` + +### Quantum Circuit Properties + +When constructing quantum circuits, there are several properties that help quantify the “size” of the circuits, and their ability to be run on a noisy quantum device. Some of these, like number of qubits, are straightforward to understand, while others like depth and number of tensor components require a bit more explanation. Here we will explain all of these properties, and, in preparation for understanding how circuits change when run on actual devices, highlight the conditions under which they change. + +Consider the following circuit: + +```python +from qiskit import QuantumCircuit +qc = QuantumCircuit(12) +for idx in range(5): + qc.h(idx) + qc.cx(idx, idx+5) + +qc.cx(1, 7) +qc.x(8) +qc.cx(1, 9) +qc.x(7) +qc.cx(1, 11) +qc.swap(6, 11) +qc.swap(6, 9) +qc.swap(6, 10) +qc.x(6) +qc.draw('mpl') +``` + +![../\_images/circuit-4.png](/images/api/qiskit/0.46/circuit-4.png) + +From the plot, it is easy to see that this circuit has 12 qubits, and a collection of Hadamard, CNOT, X, and SWAP gates. But how to quantify this programmatically? Because we can do single-qubit gates on all the qubits simultaneously, the number of qubits in this circuit is equal to the **width** of the circuit: + +```python +qc.width() +``` + +```python +12 +``` + +We can also just get the number of qubits directly: + +```python +qc.num_qubits +``` + +```python +12 +``` + + + For a quantum circuit composed from just qubits, the circuit width is equal to the number of qubits. This is the definition used in quantum computing. However, for more complicated circuits with classical registers, and classically controlled gates, this equivalence breaks down. As such, from now on we will not refer to the number of qubits in a quantum circuit as the width. + + +It is also straightforward to get the number and type of the gates in a circuit using [`QuantumCircuit.count_ops()`](qiskit.circuit.QuantumCircuit#count_ops "qiskit.circuit.QuantumCircuit.count_ops"): + +```python +qc.count_ops() +``` + +```python +OrderedDict([('cx', 8), ('h', 5), ('x', 3), ('swap', 3)]) +``` + +We can also get just the raw count of operations by computing the circuits [`QuantumCircuit.size()`](qiskit.circuit.QuantumCircuit#size "qiskit.circuit.QuantumCircuit.size"): + +```python +qc.size() +``` + +```python +19 +``` + +A particularly important circuit property is known as the circuit **depth**. The depth of a quantum circuit is a measure of how many “layers” of quantum gates, executed in parallel, it takes to complete the computation defined by the circuit. Because quantum gates take time to implement, the depth of a circuit roughly corresponds to the amount of time it takes the quantum computer to execute the circuit. Thus, the depth of a circuit is one important quantity used to measure if a quantum circuit can be run on a device. + +The depth of a quantum circuit has a mathematical definition as the longest path in a directed acyclic graph (DAG). However, such a definition is a bit hard to grasp, even for experts. Fortunately, the depth of a circuit can be easily understood by anyone familiar with playing [Tetris](https://en.wikipedia.org/wiki/Tetris). Lets see how to compute this graphically: + +![../\_images/depth.gif](/images/api/qiskit/0.46/depth.gif) + +We can verify our graphical result using [`QuantumCircuit.depth()`](qiskit.circuit.QuantumCircuit#depth "qiskit.circuit.QuantumCircuit.depth"): + +```python +qc.depth() +``` + +```python +9 +``` + +## Quantum Circuit API + +### Quantum Circuit Construction + +| | | +| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")(\*regs\[, name, global\_phase, ...]) | Create a new circuit. | +| [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")(\[size, name, bits]) | Implement a quantum register. | +| [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit")(\[register, index]) | Implement a quantum bit. | +| [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")(\[size, name, bits]) | Implement a classical register. | +| [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit")(\[register, index]) | Implement a classical bit. | +| [`AncillaRegister`](qiskit.circuit.AncillaRegister "qiskit.circuit.AncillaRegister")(\[size, name, bits]) | Implement an ancilla register. | +| [`AncillaQubit`](qiskit.circuit.AncillaQubit "qiskit.circuit.AncillaQubit")(\[register, index]) | A qubit used as ancillary qubit. | +| [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")(operation\[, qubits, clbits]) | A single instruction in a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), comprised of the `operation` and various operands. | +| [`Register`](qiskit.circuit.Register "qiskit.circuit.Register")(\[size, name, bits]) | Implement a generic register. | +| [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit")(\[register, index]) | Implement a generic bit. | + +### Gates and Instructions + +| | | +| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate")(name, num\_qubits, params\[, label, ...]) | Unitary gate. | +| [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate")(name, num\_qubits, params\[, ...]) | Controlled unitary gate. | +| [`Delay`](qiskit.circuit.Delay "qiskit.circuit.Delay")(duration\[, unit]) | Do nothing and just delay/wait/idle for a specified duration. | +| [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction")(name, num\_qubits, num\_clbits, params) | Generic quantum instruction. | +| [`InstructionSet`](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")(\*\[, resource\_requester]) | Instruction collection, and their contexts. | +| [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation")() | Quantum Operation Interface Class. | +| [`EquivalenceLibrary`](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")(\*\[, base]) | A library providing a one-way mapping of Gates to their equivalent implementations as QuantumCircuits. | + +### Control Flow Operations + +| | | +| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp")(name, num\_qubits, num\_clbits, ...) | Abstract class to encapsulate all control flow operations. | +| [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp")(condition, true\_body\[, false\_body, ...]) | A circuit operation which executes a program (`true_body`) if a provided condition (`condition`) evaluates to true, and optionally evaluates another program (`false_body`) otherwise. | +| [`WhileLoopOp`](qiskit.circuit.WhileLoopOp "qiskit.circuit.WhileLoopOp")(condition, body\[, label]) | A circuit operation which repeatedly executes a subcircuit (`body`) until a condition (`condition`) evaluates as False. | +| [`ForLoopOp`](qiskit.circuit.ForLoopOp "qiskit.circuit.ForLoopOp")(indexset, loop\_parameter, body\[, ...]) | A circuit operation which repeatedly executes a subcircuit (`body`) parameterized by a parameter `loop_parameter` through the set of integer values provided in `indexset`. | +| [`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp")(target, cases, \*\[, label]) | A circuit operation that executes one particular circuit block based on matching a given `target` against an ordered list of `values`. | +| [`BreakLoopOp`](qiskit.circuit.BreakLoopOp "qiskit.circuit.BreakLoopOp")(num\_qubits, num\_clbits\[, label]) | A circuit operation which, when encountered, jumps to the end of the nearest enclosing loop. | +| [`ContinueLoopOp`](qiskit.circuit.ContinueLoopOp "qiskit.circuit.ContinueLoopOp")(num\_qubits, num\_clbits\[, label]) | A circuit operation which, when encountered, moves to the next iteration of the nearest enclosing loop. | + +The [`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp") also understands a special value: + +**qiskit.circuit.CASE\_DEFAULT** + +A special object that represents the “default” case of a switch statement. If you use this as a case target, it must be the last case, and will match anything that wasn’t already matched. For example: + +```python +from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister +from qiskit.circuit import SwitchCaseOp, CASE_DEFAULT + +body0 = QuantumCircuit(2, 2) +body0.x(0) +body1 = QuantumCircuit(2, 2) +body1.z(0) +body2 = QuantumCircuit(2, 2) +body2.cx(0, 1) + +qr, cr = QuantumRegister(2), ClassicalRegister(2) +qc = QuantumCircuit(qr, cr) +qc.switch(cr, [(0, body0), (1, body1), (CASE_DEFAULT, body2)], qr, cr) +``` + +When using the builder interface of [`QuantumCircuit.switch()`](qiskit.circuit.QuantumCircuit#switch "qiskit.circuit.QuantumCircuit.switch"), this can also be accessed as the `DEFAULT` attribute of the bound case-builder object, such as: + +```python +from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister + +qr, cr = QuantumRegister(2), ClassicalRegister(2) +qc = QuantumCircuit(qr, cr) +with qc.switch(cr) as case: + with case(0): + qc.x(0) + with case(1): + qc.z(0) + with case(case.DEFAULT): + qc.cx(0, 1) +``` + +### Parametric Quantum Circuits + +| | | +| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")(name, \*\[, uuid]) | Parameter Class for variable parameters. | +| [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector")(name\[, length]) | ParameterVector class to quickly generate lists of parameters. | +| [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")(symbol\_map, expr) | ParameterExpression class to enable creating expressions of Parameters. | + +### Random Circuits + +### random\_circuit + + + +`qiskit.circuit.random.random_circuit(num_qubits, depth, max_operands=4, measure=False, conditional=False, reset=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/random/utils.py "view source code") + +Generate random circuit of arbitrary size and form. + +This function will generate a random circuit by randomly selecting gates from the set of standard gates in `qiskit.circuit.library.standard_gates`. For example: + +```python +from qiskit.circuit.random import random_circuit + +circ = random_circuit(2, 2, measure=True) +circ.draw(output='mpl') +``` + +![../\_images/circuit-5.png](/images/api/qiskit/0.46/circuit-5.png) + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of quantum wires +* **depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – layers of operations (i.e. critical path length) +* **max\_operands** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – maximum qubit operands of each gate (between 1 and 4) +* **measure** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, measure all qubits at the end +* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, insert middle measurements and conditionals +* **reset** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, insert middle resets +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – sets random seed (optional) + +**Returns** + +constructed circuit + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**CircuitError**](#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when invalid options given + +### Circuit Analysis + +| | | +| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| [`CommutationChecker`](qiskit.circuit.CommutationChecker "qiskit.circuit.CommutationChecker")() | This code is essentially copy-pasted from commutative\_analysis.py. | + +### Annotated Operations + +| | | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| [`AnnotatedOperation`](qiskit.circuit.AnnotatedOperation "qiskit.circuit.AnnotatedOperation")(base\_op, modifiers) | Annotated operation. | +| [`ControlModifier`](qiskit.circuit.ControlModifier "qiskit.circuit.ControlModifier")(\[num\_ctrl\_qubits, ctrl\_state]) | Control modifier: specifies that the operation is controlled by `num_ctrl_qubits` and has control state `ctrl_state`. | +| [`PowerModifier`](qiskit.circuit.PowerModifier "qiskit.circuit.PowerModifier")(power) | Power modifier: specifies that the operation is raised to the power `power`. | +| [`InverseModifier`](qiskit.circuit.InverseModifier "qiskit.circuit.InverseModifier")() | Inverse modifier: specifies that the operation is inverted. | + +### Exceptions + +Almost all circuit functions and methods will raise a [`CircuitError`](#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") when encountering an error that is particular to usage of Qiskit (as opposed to regular typing or indexing problems, which will typically raise the corresponding standard Python error). + +### CircuitError + + + +`qiskit.circuit.CircuitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/exceptions.py "view source code") + +Base class for errors raised while processing a circuit. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/circuit_classical.md b/docs/api/qiskit/0.46/circuit_classical.md new file mode 100644 index 00000000000..844cf16d370 --- /dev/null +++ b/docs/api/qiskit/0.46/circuit_classical.md @@ -0,0 +1,974 @@ +--- +title: classical +description: API reference for qiskit.circuit.classical +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.circuit.classical +--- + + + + + + + +# Classical expressions + + + +`qiskit.circuit.classical` + +This module contains an exploratory representation of runtime operations on classical values during circuit execution. + +Currently, only simple expressions on bits and registers that result in a Boolean value are supported, and these are only valid for use in the conditions of [`QuantumCircuit.if_test()`](qiskit.circuit.QuantumCircuit#if_test "qiskit.circuit.QuantumCircuit.if_test") ([`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp")) and [`QuantumCircuit.while_loop()`](qiskit.circuit.QuantumCircuit#while_loop "qiskit.circuit.QuantumCircuit.while_loop") ([`WhileLoopOp`](qiskit.circuit.WhileLoopOp "qiskit.circuit.WhileLoopOp")), and in the target of [`QuantumCircuit.switch()`](qiskit.circuit.QuantumCircuit#switch "qiskit.circuit.QuantumCircuit.switch") ([`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp")). + + + This is an exploratory module, and while we will commit to the standard Qiskit deprecation policy within it, please be aware that the module will be deliberately limited in scope at the start, and early versions may not evolve cleanly into the final version. It is possible that various components of this module will be replaced (subject to deprecations) instead of improved into a new form. + + The type system and expression tree will be expanded over time, and it is possible that the allowed types of some operations may need to change between versions of Qiskit as the classical processing capabilities develop. + + + + + + +## Expressions + + + +`qiskit.circuit.classical.expr` + +The necessary components for building expressions are all exported from the [`expr`](#module-qiskit.circuit.classical.expr "qiskit.circuit.classical.expr") namespace within [`qiskit.circuit.classical`](#module-qiskit.circuit.classical "qiskit.circuit.classical"), so you can choose whether to use qualified access (for example [`expr.Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.expr.Value")) or import the names you need directly and call them without the prefix. + +There are two pathways for constructing expressions. The classes that form [the representation of the expression system](#circuit-classical-expressions-expr-representation) have constructors that perform zero type checking; it is up to the caller to ensure that they are building valid objects. For a more user-friendly interface to direct construction, there are helper functions associated with most of the classes that do type validation and inference. These are described below, in [Construction](#circuit-classical-expressions-expr-construction). + + + +### Representation + +The expression system is based on tree representation. All nodes in the tree are final (uninheritable) instances of the abstract base class: + + + +`qiskit.circuit.classical.expr.Expr`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/expr.py "view source code") + +Root base class of all nodes in the expression tree. The base case should never be instantiated directly. + +This must not be subclassed by users; subclasses form the internal data of the representation of expressions, and it does not make sense to add more outside of Qiskit library code. + +All subclasses are responsible for setting their `type` attribute in their `__init__`, and should not call the parent initialiser. + +These objects are mutable and should not be reused in a different location without a copy. + +The entry point from general circuit objects to the expression system is by wrapping the object in a [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node and associating a [`Type`](#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type") with it. + + + +`final class qiskit.circuit.classical.expr.Var(var, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/expr.py "view source code") + +A classical variable. + +Similarly, literals used in comparison (such as integers) should be lifted to [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes with associated types. + + + +`final class qiskit.circuit.classical.expr.Value(value, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/expr.py "view source code") + +A single scalar value. + +The operations traditionally associated with pre-, post- or infix operators in programming are represented by the [`Unary`](#qiskit.circuit.classical.expr.Unary "qiskit.circuit.classical.expr.Unary") and [`Binary`](#qiskit.circuit.classical.expr.Binary "qiskit.circuit.classical.expr.Binary") nodes as appropriate. These each take an operation type code, which are exposed as enumerations inside each class as [`Unary.Op`](#qiskit.circuit.classical.expr.Unary.Op "qiskit.circuit.classical.expr.Unary.Op") and [`Binary.Op`](#qiskit.circuit.classical.expr.Binary.Op "qiskit.circuit.classical.expr.Binary.Op") respectively. + + + +`final class qiskit.circuit.classical.expr.Unary(op, operand, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/expr.py "view source code") + +A unary expression. + +**Parameters** + +* **op** ([*Unary.Op*](#qiskit.circuit.classical.expr.Unary.Op "qiskit.circuit.classical.expr.Unary.Op")) – The opcode describing which operation is being done. +* **operand** ([*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")) – The operand of the operation. +* **type** ([*Type*](#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.types.Type")) – The resolved type of the result. + + + +`Op(value)` + +Enumeration of the opcodes for unary operations. + +The bitwise negation [`BIT_NOT`](#qiskit.circuit.classical.expr.Unary.Op.BIT_NOT "qiskit.circuit.classical.expr.Unary.Op.BIT_NOT") takes a single bit or an unsigned integer of known width, and returns a value of the same type. + +The logical negation [`LOGIC_NOT`](#qiskit.circuit.classical.expr.Unary.Op.LOGIC_NOT "qiskit.circuit.classical.expr.Unary.Op.LOGIC_NOT") takes an input that is implicitly coerced to a Boolean, and returns a Boolean. + + + +### BIT\_NOT + +`= 1` + +Bitwise negation. `~operand`. + + + +### LOGIC\_NOT + +`= 2` + +Logical negation. `!operand`. + + + +`final class qiskit.circuit.classical.expr.Binary(op, left, right, type)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/expr.py "view source code") + +A binary expression. + +**Parameters** + +* **op** ([*Binary.Op*](#qiskit.circuit.classical.expr.Binary.Op "qiskit.circuit.classical.expr.Binary.Op")) – The opcode describing which operation is being done. +* **left** ([*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")) – The left-hand operand. +* **right** ([*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")) – The right-hand operand. +* **type** ([*Type*](#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.types.Type")) – The resolved type of the result. + + + +`Op(value)` + +Enumeration of the opcodes for binary operations. + +The bitwise operations [`BIT_AND`](#qiskit.circuit.classical.expr.Binary.Op.BIT_AND "qiskit.circuit.classical.expr.Binary.Op.BIT_AND"), [`BIT_OR`](#qiskit.circuit.classical.expr.Binary.Op.BIT_OR "qiskit.circuit.classical.expr.Binary.Op.BIT_OR") and [`BIT_XOR`](#qiskit.circuit.classical.expr.Binary.Op.BIT_XOR "qiskit.circuit.classical.expr.Binary.Op.BIT_XOR") apply to two operands of the same type, which must be a single bit or an unsigned integer of fixed width. The resultant type is the same as the two input types. + +The logical operations [`LOGIC_AND`](#qiskit.circuit.classical.expr.Binary.Op.LOGIC_AND "qiskit.circuit.classical.expr.Binary.Op.LOGIC_AND") and [`LOGIC_OR`](#qiskit.circuit.classical.expr.Binary.Op.LOGIC_OR "qiskit.circuit.classical.expr.Binary.Op.LOGIC_OR") first implicitly coerce their arguments to Booleans, and then apply the logical operation. The resultant type is always Boolean. + +The binary mathematical relations [`EQUAL`](#qiskit.circuit.classical.expr.Binary.Op.EQUAL "qiskit.circuit.classical.expr.Binary.Op.EQUAL"), [`NOT_EQUAL`](#qiskit.circuit.classical.expr.Binary.Op.NOT_EQUAL "qiskit.circuit.classical.expr.Binary.Op.NOT_EQUAL"), [`LESS`](#qiskit.circuit.classical.expr.Binary.Op.LESS "qiskit.circuit.classical.expr.Binary.Op.LESS"), [`LESS_EQUAL`](#qiskit.circuit.classical.expr.Binary.Op.LESS_EQUAL "qiskit.circuit.classical.expr.Binary.Op.LESS_EQUAL"), [`GREATER`](#qiskit.circuit.classical.expr.Binary.Op.GREATER "qiskit.circuit.classical.expr.Binary.Op.GREATER") and [`GREATER_EQUAL`](#qiskit.circuit.classical.expr.Binary.Op.GREATER_EQUAL "qiskit.circuit.classical.expr.Binary.Op.GREATER_EQUAL") take unsigned integers (with an implicit cast to make them the same width), and return a Boolean. + + + +### BIT\_AND + +`= 1` + +Bitwise “and”. `lhs & rhs`. + + + +### BIT\_OR + +`= 2` + +Bitwise “or”. `lhs | rhs`. + + + +### BIT\_XOR + +`= 3` + +Bitwise “exclusive or”. `lhs ^ rhs`. + + + +### LOGIC\_AND + +`= 4` + +Logical “and”. `lhs && rhs`. + + + +### LOGIC\_OR + +`= 5` + +Logical “or”. `lhs || rhs`. + + + +### EQUAL + +`= 6` + +Numeric equality. `lhs == rhs`. + + + +### NOT\_EQUAL + +`= 7` + +Numeric inequality. `lhs != rhs`. + + + +### LESS + +`= 8` + +Numeric less than. `lhs < rhs`. + + + +### LESS\_EQUAL + +`= 9` + +Numeric less than or equal to. `lhs <= rhs` + + + +### GREATER + +`= 10` + +Numeric greater than. `lhs > rhs`. + + + +### GREATER\_EQUAL + +`= 11` + +Numeric greater than or equal to. `lhs >= rhs`. + +When constructing expressions, one must ensure that the types are valid for the operation. Attempts to construct expressions with invalid types will raise a regular Python `TypeError`. + +Expressions in this system are defined to act only on certain sets of types. However, values may be cast to a suitable supertype in order to satisfy the typing requirements. In these cases, a node in the expression tree is used to represent the promotion. In all cases where operations note that they “implicitly cast” or “coerce” their arguments, the expression tree must have this node representing the conversion. + + + +`final class qiskit.circuit.classical.expr.Cast(operand, type, implicit=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/expr.py "view source code") + +A cast from one type to another, implied by the use of an expression in a different context. + + + +### Construction + +Constructing the tree representation directly is verbose and easy to make a mistake with the typing. In many cases, much of the typing can be inferred, scalar values can automatically be promoted to [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") instances, and any required promotions can be resolved into suitable [`Cast`](#qiskit.circuit.classical.expr.Cast "qiskit.circuit.classical.expr.Cast") nodes. + +The functions and methods described in this section are a more user-friendly way to build the expression tree, while staying close to the internal representation. All these functions will automatically lift valid Python scalar values into corresponding [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") or [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") objects, and will resolve any required implicit casts on your behalf. + +### lift + + + +`qiskit.circuit.classical.expr.lift(value, /, type=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Lift the given Python `value` to a [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.expr.Value") or [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var"). + +If an explicit `type` is given, the typing in the output will reflect that. + +**Examples** + +Lifting simple circuit objects to be [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var") instances: + +```python +>>> from qiskit.circuit import Clbit, ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.lift(Clbit()) +Var(, Bool()) +>>> expr.lift(ClassicalRegister(3, "c")) +Var(ClassicalRegister(3, "c"), Uint(3)) +``` + +The type of the return value can be influenced, if the given value could be interpreted losslessly as the given type (use [`cast()`](#qiskit.circuit.classical.expr.cast "qiskit.circuit.classical.expr.cast") to perform a full set of casting operations, include lossy ones): + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr, types +>>> expr.lift(ClassicalRegister(3, "c"), types.Uint(5)) +Var(ClassicalRegister(3, "c"), Uint(5)) +>>> expr.lift(5, types.Uint(4)) +Value(5, Uint(4)) +``` + +**Return type** + +[Expr](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") + +You can manually specify casts in cases where the cast is allowed in explicit form, but may be lossy (such as the cast of a higher precision [`Uint`](#qiskit.circuit.classical.types.Uint "qiskit.circuit.classical.types.Uint") to a lower precision one). + +### cast + + + +`qiskit.circuit.classical.expr.cast(operand, type, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create an explicit cast from the given value to the given type. + +**Examples** + +Add an explicit cast node that explicitly casts a higher precision type to a lower precision one: + +```python +>>> from qiskit.circuit.classical import expr, types +>>> value = expr.value(5, types.Uint(32)) +>>> expr.cast(value, types.Uint(8)) +Cast(Value(5, types.Uint(32)), types.Uint(8), implicit=False) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +There are helper constructor functions for each of the unary operations. + +### bit\_not + + + +`qiskit.circuit.classical.expr.bit_not(operand, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a bitwise ‘not’ expression node from the given value, resolving any implicit casts and lifting the value into a [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") node if required. + +**Examples** + +Bitwise negation of a [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister"): + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.bit_not(ClassicalRegister(3, "c")) +Unary(Unary.Op.BIT_NOT, Var(ClassicalRegister(3, 'c'), Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### logic\_not + + + +`qiskit.circuit.classical.expr.logic_not(operand, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a logical ‘not’ expression node from the given value, resolving any implicit casts and lifting the value into a [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") node if required. + +**Examples** + +Logical negation of a [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister"): + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.logic_not(ClassicalRegister(3, "c")) +Unary(Unary.Op.LOGIC_NOT, Cast(Var(ClassicalRegister(3, 'c'), Uint(3)), Bool(), implicit=True), Bool()) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +Similarly, the binary operations and relations have helper functions defined. + +### bit\_and + + + +`qiskit.circuit.classical.expr.bit_and(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a bitwise ‘and’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Bitwise ‘and’ of a classical register and an integer literal: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.bit_and(ClassicalRegister(3, "c"), 0b111) +Binary(Binary.Op.BIT_AND, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(7, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### bit\_or + + + +`qiskit.circuit.classical.expr.bit_or(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a bitwise ‘or’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Bitwise ‘or’ of a classical register and an integer literal: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.bit_or(ClassicalRegister(3, "c"), 0b101) +Binary(Binary.Op.BIT_OR, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(5, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### bit\_xor + + + +`qiskit.circuit.classical.expr.bit_xor(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a bitwise ‘exclusive or’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Bitwise ‘exclusive or’ of a classical register and an integer literal: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.bit_xor(ClassicalRegister(3, "c"), 0b101) +Binary(Binary.Op.BIT_XOR, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(5, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### logic\_and + + + +`qiskit.circuit.classical.expr.logic_and(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a logical ‘and’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Logical ‘and’ of two classical bits: + +```python +>>> from qiskit.circuit import Clbit +>>> from qiskit.circuit.classical import expr +>>> expr.logical_and(Clbit(), Clbit()) +Binary(Binary.Op.LOGIC_AND, Var(, Bool()), Var(, Bool()), Bool()) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### logic\_or + + + +`qiskit.circuit.classical.expr.logic_or(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a logical ‘or’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Logical ‘or’ of two classical bits + +```python +>>> from qiskit.circuit import Clbit +>>> from qiskit.circuit.classical import expr +>>> expr.logical_and(Clbit(), Clbit()) +Binary(Binary.Op.LOGIC_OR, Var(, Bool()), Var(, Bool()), Bool()) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### equal + + + +`qiskit.circuit.classical.expr.equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create an ‘equal’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Equality between a classical register and an integer: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.equal(ClassicalRegister(3, "c"), 7) +Binary(Binary.Op.EQUAL, Var(ClassicalRegister(3, "c"), Uint(3)), Value(7, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### not\_equal + + + +`qiskit.circuit.classical.expr.not_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a ‘not equal’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Inequality between a classical register and an integer: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.not_equal(ClassicalRegister(3, "c"), 7) +Binary(Binary.Op.NOT_EQUAL, Var(ClassicalRegister(3, "c"), Uint(3)), Value(7, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### less + + + +`qiskit.circuit.classical.expr.less(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a ‘less than’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Query if a classical register is less than an integer: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.less(ClassicalRegister(3, "c"), 5) +Binary(Binary.Op.LESS, Var(ClassicalRegister(3, "c"), Uint(3)), Value(5, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### less\_equal + + + +`qiskit.circuit.classical.expr.less_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a ‘less than or equal to’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Query if a classical register is less than or equal to another: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.less(ClassicalRegister(3, "a"), ClassicalRegister(3, "b")) +Binary(Binary.Op.LESS_EQUAL, Var(ClassicalRegister(3, "a"), Uint(3)), Var(ClassicalRegister(3, "b"), Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### greater + + + +`qiskit.circuit.classical.expr.greater(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a ‘greater than’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Query if a classical register is greater than an integer: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.less(ClassicalRegister(3, "c"), 5) +Binary(Binary.Op.GREATER, Var(ClassicalRegister(3, "c"), Uint(3)), Value(5, Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +### greater\_equal + + + +`qiskit.circuit.classical.expr.greater_equal(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Create a ‘greater than or equal to’ expression node from the given value, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required. + +**Examples** + +Query if a classical register is greater than or equal to another: + +```python +>>> from qiskit.circuit import ClassicalRegister +>>> from qiskit.circuit.classical import expr +>>> expr.less(ClassicalRegister(3, "a"), ClassicalRegister(3, "b")) +Binary(Binary.Op.GREATER_EQUAL, Var(ClassicalRegister(3, "a"), Uint(3)), Var(ClassicalRegister(3, "b"), Uint(3)), Uint(3)) +``` + +**Return type** + +[*Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") + +Qiskit’s legacy method for specifying equality conditions for use in conditionals is to use a two-tuple of a [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") or [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") and an integer. This represents an exact equality condition, and there are no ways to specify any other relations. The helper function [`lift_legacy_condition()`](#qiskit.circuit.classical.expr.lift_legacy_condition "qiskit.circuit.classical.expr.lift_legacy_condition") converts this legacy format into the new expression syntax. + +### lift\_legacy\_condition + + + +`qiskit.circuit.classical.expr.lift_legacy_condition(condition, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/constructors.py "view source code") + +Lift a legacy two-tuple equality condition into a new-style [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr"). + +**Examples** + +Taking an old-style conditional instruction and getting an [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") from its condition: + +```python +from qiskit.circuit import ClassicalRegister +from qiskit.circuit.library import HGate +from qiskit.circuit.classical import expr + +cr = ClassicalRegister(2) +instr = HGate().c_if(cr, 3) + +lifted = expr.lift_legacy_condition(instr.condition) +``` + +**Return type** + +[Expr](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") + +### Working with the expression tree + +A typical consumer of the expression tree wants to recursively walk through the tree, potentially statefully, acting on each node differently depending on its type. This is naturally a double-dispatch problem; the logic of ‘what is to be done’ is likely stateful and users should be free to define their own operations, yet each node defines ‘what is being acted on’. We enable this double dispatch by providing a base visitor class for the expression tree. + + + +`qiskit.circuit.classical.expr.ExprVisitor`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/visitors.py "view source code") + +Base class for visitors to the [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") tree. Subclasses should override whichever of the `visit_*` methods that they are able to handle, and should be organised such that non-existent methods will never be called. + +### visit\_binary + + + +`visit_binary(node, /)` + +**Return type** + +*\_T\_co* + +### visit\_cast + + + +`visit_cast(node, /)` + +**Return type** + +*\_T\_co* + +### visit\_generic + + + +`visit_generic(node, /)` + +**Return type** + +*\_T\_co* + +### visit\_unary + + + +`visit_unary(node, /)` + +**Return type** + +*\_T\_co* + +### visit\_value + + + +`visit_value(node, /)` + +**Return type** + +*\_T\_co* + +### visit\_var + + + +`visit_var(node, /)` + +**Return type** + +*\_T\_co* + +Consumers of the expression tree should subclass the visitor, and override the `visit_*` methods that they wish to handle. Any non-overridden methods will call [`visit_generic()`](#qiskit.circuit.classical.expr.ExprVisitor.visit_generic "qiskit.circuit.classical.expr.ExprVisitor.visit_generic"), which unless overridden will raise a `RuntimeError` to ensure that you are aware if new nodes have been added to the expression tree that you are not yet handling. + +For the convenience of simple visitors that only need to inspect the variables in an expression and not the general structure, the iterator method [`iter_vars()`](#qiskit.circuit.classical.expr.iter_vars "qiskit.circuit.classical.expr.iter_vars") is provided. + +### iter\_vars + + + +`qiskit.circuit.classical.expr.iter_vars(node)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/visitors.py "view source code") + +Get an iterator over the [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var") nodes referenced at any level in the given [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr"). + +**Examples** + +Print out the name of each [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") encountered: + +```python +from qiskit.circuit import ClassicalRegister +from qiskit.circuit.classical import expr + +cr1 = ClassicalRegister(3, "a") +cr2 = ClassicalRegister(3, "b") + +for node in expr.iter_vars(expr.bit_and(expr.bit_not(cr1), cr2)): + if isinstance(node.var, ClassicalRegister): + print(node.var.name) +``` + +**Return type** + +[*Iterator*](https://docs.python.org/3/library/typing.html#typing.Iterator "(in Python v3.12)")\[[*Var*](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")] + +Two expressions can be compared for direct structural equality by using the built-in Python `==` operator. In general, though, one might want to compare two expressions slightly more semantically, allowing that the [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes inside them are bound to different memory-location descriptions between two different circuits. In this case, one can use [`structurally_equivalent()`](#qiskit.circuit.classical.expr.structurally_equivalent "qiskit.circuit.classical.expr.structurally_equivalent") with two suitable “key” functions to do the comparison. + +### structurally\_equivalent + + + +`qiskit.circuit.classical.expr.structurally_equivalent(left, right, left_var_key=None, right_var_key=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/expr/visitors.py "view source code") + +Do these two expressions have exactly the same tree structure, up to some key function for the [`Var`](#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var") objects? + +In other words, are these two expressions the exact same trees, except we compare the `Var.var` fields by calling the appropriate `*_var_key` function on them, and comparing that output for equality. This function does not allow any semantic “equivalences” such as asserting that `a == b` is equivalent to `b == a`; the evaluation order of the operands could, in general, cause such a statement to be false (consider hypothetical `extern` functions that access global state). + +There’s no requirements on the key functions, except that their outputs should have general `__eq__` methods. If a key function returns `None`, the variable will be used verbatim instead. + +**Parameters** + +* **left** ([*expr.Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr")) – one of the [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") nodes. +* **right** ([*expr.Expr*](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr")) – the other [`Expr`](#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.expr.Expr") node. +* **left\_var\_key** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*],* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – a callable whose output should be used when comparing `Var.var` attributes. If this argument is `None` or its output is `None` for a given variable in `left`, the variable will be used verbatim. +* **right\_var\_key** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*],* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – same as `left_var_key`, but used on the variables in `right` instead. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +**Examples** + +Comparing two expressions for structural equivalence, with no remapping of the variables. These are different because the different [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") instances compare differently: + +```python +>>> from qiskit.circuit import Clbit +>>> from qiskit.circuit.classical import expr +>>> left_bits = [Clbit(), Clbit()] +>>> right_bits = [Clbit(), Clbit()] +>>> left = expr.logic_and(expr.logic_not(left_bits[0]), left_bits[1]) +>>> right = expr.logic_and(expr.logic_not(right_bits[0]), right_bits[1]) +>>> expr.structurally_equivalent(left, right) +False +``` + +Comparing the same two expressions, but this time using mapping functions that associate the bits with simple indices: + +```python +>>> left_key = {var: i for i, var in enumerate(left_bits)}.get +>>> right_key = {var: i for i, var in enumerate(right_bits)}.get +>>> expr.structurally_equivalent(left, right, left_key, right_key) +True +``` + + + + + +## Typing + + + +`qiskit.circuit.classical.types` + +The type system of the expression tree is exposed through this module. This is inherently linked to the expression system in the [`expr`](#module-qiskit.circuit.classical.expr "qiskit.circuit.classical.expr") module, as most expressions can only be understood with the context of the types that they act on. + +All types inherit from an abstract base class: + + + +`qiskit.circuit.classical.types.Type`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/types.py "view source code") + +Root base class of all nodes in the type tree. The base case should never be instantiated directly. + +This must not be subclassed by users; subclasses form the internal data of the representation of expressions, and it does not make sense to add more outside of Qiskit library code. + +Types should be considered immutable objects, and you must not mutate them. It is permissible to reuse a [`Type`](#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type") that you take from another object without copying it, and generally this will be the best approach for performance. [`Type`](#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type") objects are designed to be small amounts of data, and it’s best to point to the same instance of the data where possible rather than heap-allocating a new version of the same thing. Where possible, the class constructors will return singleton instances to facilitate this. + +The two different types available are for Booleans (corresponding to [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") and the literals `True` and `False`), and unsigned integers (corresponding to [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") and Python integers). + + + +`final class qiskit.circuit.classical.types.Bool`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/types.py "view source code") + +The Boolean type. This has exactly two values: `True` and `False`. + + + +`final class qiskit.circuit.classical.types.Uint(width)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/types.py "view source code") + +An unsigned integer of fixed bit width. + +Note that [`Uint`](#qiskit.circuit.classical.types.Uint "qiskit.circuit.classical.types.Uint") defines a family of types parametrised by their width; it is not one single type, which may be slightly different to the ‘classical’ programming languages you are used to. + +There are some functions on these types exposed here as well. These are mostly expected to be used only in manipulations of the expression tree; users who are building expressions using the [user-facing construction interface](#circuit-classical-expressions-expr-construction) should not need to use these. + +The type system is equipped with a partial ordering, where $a < b$ is interpreted as “$a$ is a strict subtype of $b$”. Note that the partial ordering is a subset of the directed graph that describes the allowed explicit casting operations between types. The partial ordering defines when one type may be lossless directly interpreted as another. + +The low-level interface to querying the subtyping relationship is the [`order()`](#qiskit.circuit.classical.types.order "qiskit.circuit.classical.types.order") function. + +### order + + + +`qiskit.circuit.classical.types.order(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/ordering.py "view source code") + +Get the ordering relationship between the two types as an enumeration value. + +**Examples** + +Compare two [`Uint`](#qiskit.circuit.classical.types.Uint "qiskit.circuit.classical.types.Uint") types of different widths: + +```python +>>> from qiskit.circuit.classical import types +>>> types.order(types.Uint(8), types.Uint(16)) +Ordering.LESS +``` + +Compare two types that have no ordering between them: + +```python +>>> types.order(types.Uint(8), types.Bool()) +Ordering.NONE +``` + +**Return type** + +[*Ordering*](#qiskit.circuit.classical.types.Ordering "qiskit.circuit.classical.types.ordering.Ordering") + +The return value is an enumeration [`Ordering`](#qiskit.circuit.classical.types.Ordering "qiskit.circuit.classical.types.Ordering") that describes what, if any, subtyping relationship exists between the two types. + + + +`qiskit.circuit.classical.types.Ordering(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/ordering.py "view source code") + +Enumeration listing the possible relations between two types. Types only have a partial ordering, so it’s possible for two types to have no sub-typing relationship. + +Note that the sub-/supertyping relationship is not the same as whether a type can be explicitly cast from one to another. + +Some helper methods are then defined in terms of this low-level [`order()`](#qiskit.circuit.classical.types.order "qiskit.circuit.classical.types.order") primitive: + +### is\_subtype + + + +`qiskit.circuit.classical.types.is_subtype(left, right, /, strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/ordering.py "view source code") + +Does the relation $\text{left} \le \text{right}$ hold? If there is no ordering relation between the two types, then this returns `False`. If `strict`, then the equality is also forbidden. + +**Examples** + +Check if one type is a subclass of another: + +```python +>>> from qiskit.circuit.classical import types +>>> types.is_subtype(types.Uint(8), types.Uint(16)) +True +``` + +Check if one type is a strict subclass of another: + +```python +>>> types.is_subtype(types.Bool(), types.Bool()) +True +>>> types.is_subtype(types.Bool(), types.Bool(), strict=True) +False +``` + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_supertype + + + +`qiskit.circuit.classical.types.is_supertype(left, right, /, strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/ordering.py "view source code") + +Does the relation $\text{left} \ge \text{right}$ hold? If there is no ordering relation between the two types, then this returns `False`. If `strict`, then the equality is also forbidden. + +**Examples** + +Check if one type is a superclass of another: + +```python +>>> from qiskit.circuit.classical import types +>>> types.is_supertype(types.Uint(8), types.Uint(16)) +False +``` + +Check if one type is a strict superclass of another: + +```python +>>> types.is_supertype(types.Bool(), types.Bool()) +True +>>> types.is_supertype(types.Bool(), types.Bool(), strict=True) +False +``` + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### greater + + + +`qiskit.circuit.classical.types.greater(left, right, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classical/types/ordering.py "view source code") + +Get the greater of the two types, assuming that there is an ordering relation between them. Technically, this is a slightly restricted version of the concept of the ‘meet’ of the two types in that the return value must be one of the inputs. In practice in the type system there is no concept of a ‘sum’ type, so the ‘meet’ exists if and only if there is an ordering between the two types, and is equal to the greater of the two types. + +**Returns** + +The greater of the two types. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – if there is no ordering relation between the two types. + +**Return type** + +[*Type*](#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.types.Type") + +**Examples** + +Find the greater of two [`Uint`](#qiskit.circuit.classical.types.Uint "qiskit.circuit.classical.types.Uint") types: + +```python +>>> from qiskit.circuit.classical import types +>>> types.greater(types.Uint(8), types.Uint(16)) +types.Uint(16) +``` + diff --git a/docs/api/qiskit/0.46/circuit_library.md b/docs/api/qiskit/0.46/circuit_library.md new file mode 100644 index 00000000000..463777ab094 --- /dev/null +++ b/docs/api/qiskit/0.46/circuit_library.md @@ -0,0 +1,1292 @@ +--- +title: library +description: API reference for qiskit.circuit.library +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.circuit.library +--- + + + + + + + +# Circuit Library + + + +`qiskit.circuit.library` + +The circuit library is a collection of well-studied and valuable circuits, directives, and gates. We call them valuable for different reasons, for instance they can serve as building blocks for algorithms or they are circuits that we think are hard to simulate classically. + +Each element can be plugged into a circuit using the [`QuantumCircuit.append()`](qiskit.circuit.QuantumCircuit#append "qiskit.circuit.QuantumCircuit.append") method and so the circuit library allows users to program at higher levels of abstraction. For example, to append a multi-controlled CNOT: + +```python +from qiskit.circuit.library import MCXGate +gate = MCXGate(4) + +from qiskit import QuantumCircuit +circuit = QuantumCircuit(5) +circuit.append(gate, [0, 1, 4, 2, 3]) +circuit.draw('mpl') +``` + +![../\_images/circuit\_library-1.png](/images/api/qiskit/0.46/circuit_library-1.png) + +The library is organized in several sections. + +## Standard gates + +These operations are reversible unitary gates and they all subclass [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"). As a consequence, they all have the methods [`to_matrix()`](qiskit.circuit.Gate#to_matrix "qiskit.circuit.Gate.to_matrix"), [`power()`](qiskit.circuit.Gate#power "qiskit.circuit.Gate.power"), and [`control()`](qiskit.circuit.Gate#control "qiskit.circuit.Gate.control"), which we can generally only apply to unitary operations. + +For example: + +```python +from qiskit.circuit.library import XGate +gate = XGate() +print(gate.to_matrix()) # X gate +print(gate.power(1/2).to_matrix()) # √X gate +print(gate.control(1).to_matrix()) # CX (controlled X) gate +``` + +```python +[[0.+0.j 1.+0.j] + [1.+0.j 0.+0.j]] +[[0.5+0.5j 0.5-0.5j] + [0.5-0.5j 0.5+0.5j]] +[[1.+0.j 0.+0.j 0.+0.j 0.+0.j] + [0.+0.j 0.+0.j 0.+0.j 1.+0.j] + [0.+0.j 0.+0.j 1.+0.j 0.+0.j] + [0.+0.j 1.+0.j 0.+0.j 0.+0.j]] +``` + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| [`C3XGate`](qiskit.circuit.library.C3XGate "qiskit.circuit.library.C3XGate")(\*args\[, \_force\_mutable]) | The X gate controlled on 3 qubits. | +| [`C3SXGate`](qiskit.circuit.library.C3SXGate "qiskit.circuit.library.C3SXGate")(\*args\[, \_force\_mutable]) | The 3-qubit controlled sqrt-X gate. | +| [`C4XGate`](qiskit.circuit.library.C4XGate "qiskit.circuit.library.C4XGate")(\*args\[, \_force\_mutable]) | The 4-qubit controlled X gate. | +| [`CCXGate`](qiskit.circuit.library.CCXGate "qiskit.circuit.library.CCXGate")(\*args\[, \_force\_mutable]) | CCX gate, also known as Toffoli gate. | +| [`DCXGate`](qiskit.circuit.library.DCXGate "qiskit.circuit.library.DCXGate")(\*args\[, \_force\_mutable]) | Double-CNOT gate. | +| [`CHGate`](qiskit.circuit.library.CHGate "qiskit.circuit.library.CHGate")(\*args\[, \_force\_mutable]) | Controlled-Hadamard gate. | +| [`CPhaseGate`](qiskit.circuit.library.CPhaseGate "qiskit.circuit.library.CPhaseGate")(theta\[, label, ctrl\_state, ...]) | Controlled-Phase gate. | +| [`CRXGate`](qiskit.circuit.library.CRXGate "qiskit.circuit.library.CRXGate")(theta\[, label, ctrl\_state, ...]) | Controlled-RX gate. | +| [`CRYGate`](qiskit.circuit.library.CRYGate "qiskit.circuit.library.CRYGate")(theta\[, label, ctrl\_state, ...]) | Controlled-RY gate. | +| [`CRZGate`](qiskit.circuit.library.CRZGate "qiskit.circuit.library.CRZGate")(theta\[, label, ctrl\_state, ...]) | Controlled-RZ gate. | +| [`CSGate`](qiskit.circuit.library.CSGate "qiskit.circuit.library.CSGate")(\*args\[, \_force\_mutable]) | Controlled-S gate. | +| [`CSdgGate`](qiskit.circuit.library.CSdgGate "qiskit.circuit.library.CSdgGate")(\*args\[, \_force\_mutable]) | Controlled-S^dagger gate. | +| [`CSwapGate`](qiskit.circuit.library.CSwapGate "qiskit.circuit.library.CSwapGate")(\*args\[, \_force\_mutable]) | Controlled-SWAP gate, also known as the Fredkin gate. | +| [`CSXGate`](qiskit.circuit.library.CSXGate "qiskit.circuit.library.CSXGate")(\*args\[, \_force\_mutable]) | Controlled-√X gate. | +| [`CUGate`](qiskit.circuit.library.CUGate "qiskit.circuit.library.CUGate")(theta, phi, lam, gamma\[, label, ...]) | Controlled-U gate (4-parameter two-qubit gate). | +| [`CU1Gate`](qiskit.circuit.library.CU1Gate "qiskit.circuit.library.CU1Gate")(theta\[, label, ctrl\_state, ...]) | Controlled-U1 gate. | +| [`CU3Gate`](qiskit.circuit.library.CU3Gate "qiskit.circuit.library.CU3Gate")(theta, phi, lam\[, label, ...]) | Controlled-U3 gate (3-parameter two-qubit gate). | +| [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate")(\*args\[, \_force\_mutable]) | Controlled-X gate. | +| [`CYGate`](qiskit.circuit.library.CYGate "qiskit.circuit.library.CYGate")(\*args\[, \_force\_mutable]) | Controlled-Y gate. | +| [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate")(\*args\[, \_force\_mutable]) | Controlled-Z gate. | +| [`CCZGate`](qiskit.circuit.library.CCZGate "qiskit.circuit.library.CCZGate")(\*args\[, \_force\_mutable]) | CCZ gate. | +| [`ECRGate`](qiskit.circuit.library.ECRGate "qiskit.circuit.library.ECRGate")(\*args\[, \_force\_mutable]) | An echoed cross-resonance gate. | +| [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate")(\*args\[, \_force\_mutable]) | Single-qubit Hadamard gate. | +| [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate")(\*args\[, \_force\_mutable]) | Identity gate. | +| [`MSGate`](qiskit.circuit.library.MSGate "qiskit.circuit.library.MSGate")(num\_qubits, theta\[, label]) | MSGate has been deprecated. | +| [`PhaseGate`](qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate")(theta\[, label, duration, unit]) | Single-qubit rotation about the Z axis. | +| [`RCCXGate`](qiskit.circuit.library.RCCXGate "qiskit.circuit.library.RCCXGate")(\*args\[, \_force\_mutable]) | The simplified Toffoli gate, also referred to as Margolus gate. | +| [`RC3XGate`](qiskit.circuit.library.RC3XGate "qiskit.circuit.library.RC3XGate")(\*args\[, \_force\_mutable]) | The simplified 3-controlled Toffoli gate. | +| [`RGate`](qiskit.circuit.library.RGate "qiskit.circuit.library.RGate")(theta, phi\[, label, duration, unit]) | Rotation θ around the cos(φ)x + sin(φ)y axis. | +| [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate")(theta\[, label, duration, unit]) | Single-qubit rotation about the X axis. | +| [`RXXGate`](qiskit.circuit.library.RXXGate "qiskit.circuit.library.RXXGate")(theta\[, label, duration, unit]) | A parametric 2-qubit $X \otimes X$ interaction (rotation about XX). | +| [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.RYGate")(theta\[, label, duration, unit]) | Single-qubit rotation about the Y axis. | +| [`RYYGate`](qiskit.circuit.library.RYYGate "qiskit.circuit.library.RYYGate")(theta\[, label, duration, unit]) | A parametric 2-qubit $Y \otimes Y$ interaction (rotation about YY). | +| [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate")(phi\[, label, duration, unit]) | Single-qubit rotation about the Z axis. | +| [`RZZGate`](qiskit.circuit.library.RZZGate "qiskit.circuit.library.RZZGate")(theta\[, label, duration, unit]) | A parametric 2-qubit $Z \otimes Z$ interaction (rotation about ZZ). | +| [`RZXGate`](qiskit.circuit.library.RZXGate "qiskit.circuit.library.RZXGate")(theta\[, label, duration, unit]) | A parametric 2-qubit $Z \otimes X$ interaction (rotation about ZX). | +| [`XXMinusYYGate`](qiskit.circuit.library.XXMinusYYGate "qiskit.circuit.library.XXMinusYYGate")(theta\[, beta, label, ...]) | XX-YY interaction gate. | +| [`XXPlusYYGate`](qiskit.circuit.library.XXPlusYYGate "qiskit.circuit.library.XXPlusYYGate")(theta\[, beta, label, duration, ...]) | XX+YY interaction gate. | +| [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate")(\*args\[, \_force\_mutable]) | Single qubit S gate (Z\*\*0.5). | +| [`SdgGate`](qiskit.circuit.library.SdgGate "qiskit.circuit.library.SdgGate")(\*args\[, \_force\_mutable]) | Single qubit S-adjoint gate (\~Z\*\*0.5). | +| [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")(\*args\[, \_force\_mutable]) | The SWAP gate. | +| [`iSwapGate`](qiskit.circuit.library.iSwapGate "qiskit.circuit.library.iSwapGate")(\*args\[, \_force\_mutable]) | iSWAP gate. | +| [`SXGate`](qiskit.circuit.library.SXGate "qiskit.circuit.library.SXGate")(\*args\[, \_force\_mutable]) | The single-qubit Sqrt(X) gate ($\sqrt{X}$). | +| [`SXdgGate`](qiskit.circuit.library.SXdgGate "qiskit.circuit.library.SXdgGate")(\*args\[, \_force\_mutable]) | The inverse single-qubit Sqrt(X) gate. | +| [`TGate`](qiskit.circuit.library.TGate "qiskit.circuit.library.TGate")(\*args\[, \_force\_mutable]) | Single qubit T gate (Z\*\*0.25). | +| [`TdgGate`](qiskit.circuit.library.TdgGate "qiskit.circuit.library.TdgGate")(\*args\[, \_force\_mutable]) | Single qubit T-adjoint gate (\~Z\*\*0.25). | +| [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate")(theta, phi, lam\[, label, duration, unit]) | Generic single-qubit rotation gate with 3 Euler angles. | +| [`U1Gate`](qiskit.circuit.library.U1Gate "qiskit.circuit.library.U1Gate")(theta\[, label, duration, unit]) | Single-qubit rotation about the Z axis. | +| [`U2Gate`](qiskit.circuit.library.U2Gate "qiskit.circuit.library.U2Gate")(phi, lam\[, label, duration, unit]) | Single-qubit rotation about the X+Z axis. | +| [`U3Gate`](qiskit.circuit.library.U3Gate "qiskit.circuit.library.U3Gate")(theta, phi, lam\[, label, duration, unit]) | Generic single-qubit rotation gate with 3 Euler angles. | +| [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate")(\*args\[, \_force\_mutable]) | The single-qubit Pauli-X gate ($\sigma_x$). | +| [`YGate`](qiskit.circuit.library.YGate "qiskit.circuit.library.YGate")(\*args\[, \_force\_mutable]) | The single-qubit Pauli-Y gate ($\sigma_y$). | +| [`ZGate`](qiskit.circuit.library.ZGate "qiskit.circuit.library.ZGate")(\*args\[, \_force\_mutable]) | The single-qubit Pauli-Z gate ($\sigma_z$). | +| [`GlobalPhaseGate`](qiskit.circuit.library.GlobalPhaseGate "qiskit.circuit.library.GlobalPhaseGate")(phase\[, label, duration, unit]) | The global phase gate ($e^{i\theta}$). | + +## Standard Directives + +Directives are operations to the quantum stack that are meant to be interpreted by the backend or the transpiler. In general, the transpiler or backend might optionally ignore them if there is no implementation for them. + +| | | +| --------------------------------------------------------------------------------------------------- | -------------------- | +| [`Barrier`](qiskit.circuit.library.Barrier "qiskit.circuit.library.Barrier")(num\_qubits\[, label]) | Barrier instruction. | + +## Standard Operations + +Operations are non-reversible changes in the quantum state of the circuit. + +| | | +| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure")(\[label, duration, unit]) | Quantum measurement in the computational basis. | +| [`Reset`](qiskit.circuit.library.Reset "qiskit.circuit.library.Reset")(\[label, duration, unit]) | Qubit reset. | + +## Generalized Gates + +These “gates” (many are [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") subclasses) allow to set the amount of qubits involved at instantiation time. + +```python +from qiskit.circuit.library import Diagonal + +diagonal = Diagonal([1, 1]) +print(diagonal.num_qubits) + +diagonal = Diagonal([1, 1, 1, 1]) +print(diagonal.num_qubits) +``` + +```python +1 +2 +``` + +| | | | | +| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | - | ----------------------------------- | +| [`Diagonal`](qiskit.circuit.library.Diagonal "qiskit.circuit.library.Diagonal")(diag) | Diagonal circuit. | | | +| [`DiagonalGate`](qiskit.circuit.library.DiagonalGate "qiskit.circuit.library.DiagonalGate")(diag) | Gate implementing a diagonal transformation. | | | +| [`MCMT`](qiskit.circuit.library.MCMT "qiskit.circuit.library.MCMT")(gate, num\_ctrl\_qubits, num\_target\_qubits) | The multi-controlled multi-target gate, for an arbitrary singly controlled target gate. | | | +| [`MCMTVChain`](qiskit.circuit.library.MCMTVChain "qiskit.circuit.library.MCMTVChain")(gate, num\_ctrl\_qubits, ...) | The MCMT implementation using the CCX V-chain. | | | +| [`Permutation`](qiskit.circuit.library.Permutation "qiskit.circuit.library.Permutation")(num\_qubits\[, pattern, seed]) | An n\_qubit circuit that permutes qubits. | | | +| [`PermutationGate`](qiskit.circuit.library.PermutationGate "qiskit.circuit.library.PermutationGate")(pattern) | A gate that permutes qubits. | | | +| [`GMS`](qiskit.circuit.library.GMS "qiskit.circuit.library.GMS")(num\_qubits, theta) | Global Mølmer–Sørensen gate. | | | +| [`GR`](qiskit.circuit.library.GR "qiskit.circuit.library.GR")(num\_qubits, theta, phi) | Global R gate. | | | +| [`GRX`](qiskit.circuit.library.GRX "qiskit.circuit.library.GRX")(num\_qubits, theta) | Global RX gate. | | | +| [`GRY`](qiskit.circuit.library.GRY "qiskit.circuit.library.GRY")(num\_qubits, theta) | Global RY gate. | | | +| [`GRZ`](qiskit.circuit.library.GRZ "qiskit.circuit.library.GRZ")(num\_qubits, phi) | Global RZ gate. | | | +| [`MCPhaseGate`](qiskit.circuit.library.MCPhaseGate "qiskit.circuit.library.MCPhaseGate")(lam, num\_ctrl\_qubits\[, label, ...]) | Multi-controlled-Phase gate. | | | +| [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.MCXGate")(\[num\_ctrl\_qubits, label, ...]) | The general, multi-controlled X gate. | | | +| [`MCXGrayCode`](qiskit.circuit.library.MCXGrayCode "qiskit.circuit.library.MCXGrayCode")(\[num\_ctrl\_qubits, label, ...]) | Implement the multi-controlled X gate using the Gray code. | | | +| [`MCXRecursive`](qiskit.circuit.library.MCXRecursive "qiskit.circuit.library.MCXRecursive")(\[num\_ctrl\_qubits, label, ...]) | Implement the multi-controlled X gate using recursion. | | | +| [`MCXVChain`](qiskit.circuit.library.MCXVChain "qiskit.circuit.library.MCXVChain")(\[num\_ctrl\_qubits, dirty\_ancillas, ...]) | Implement the multi-controlled X gate using a V-chain of CX gates. | | | +| [`RVGate`](qiskit.circuit.library.RVGate "qiskit.circuit.library.RVGate")(v\_x, v\_y, v\_z\[, basis]) | Rotation around arbitrary rotation axis $v$ where \$ | v | \$ is angle of rotation in radians. | +| [`PauliGate`](qiskit.circuit.library.PauliGate "qiskit.circuit.library.PauliGate")(label) | A multi-qubit Pauli gate. | | | +| [`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction")(linear\[, validate\_input]) | A linear reversible circuit on n qubits. | | | +| [`Isometry`](qiskit.circuit.library.Isometry "qiskit.circuit.library.Isometry")(isometry, num\_ancillas\_zero, ...\[, ...]) | Decomposition of arbitrary isometries from $m$ to $n$ qubits. | | | +| [`UnitaryGate`](qiskit.circuit.library.UnitaryGate "qiskit.circuit.library.UnitaryGate")(data\[, label, check\_input]) | Class quantum gates specified by a unitary matrix. | | | +| [`UCGate`](qiskit.circuit.library.UCGate "qiskit.circuit.library.UCGate")(gate\_list\[, up\_to\_diagonal]) | Uniformly controlled gate (also called multiplexed gate). | | | +| [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.UCPauliRotGate")(angle\_list, rot\_axis) | Uniformly controlled Pauli rotations. | | | +| [`UCRXGate`](qiskit.circuit.library.UCRXGate "qiskit.circuit.library.UCRXGate")(angle\_list) | Uniformly controlled Pauli-X rotations. | | | +| [`UCRYGate`](qiskit.circuit.library.UCRYGate "qiskit.circuit.library.UCRYGate")(angle\_list) | Uniformly controlled Pauli-Y rotations. | | | +| [`UCRZGate`](qiskit.circuit.library.UCRZGate "qiskit.circuit.library.UCRZGate")(angle\_list) | Uniformly controlled Pauli-Z rotations. | | | + +## Boolean Logic Circuits + +These are [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") subclasses that implement boolean logic operations, such as the logical or of a set of qubit states. + +| | | +| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | +| [`AND`](qiskit.circuit.library.AND "qiskit.circuit.library.AND")(num\_variable\_qubits\[, flags, mcx\_mode]) | A circuit implementing the logical AND operation on a number of qubits. | +| [`OR`](qiskit.circuit.library.OR "qiskit.circuit.library.OR")(num\_variable\_qubits\[, flags, mcx\_mode]) | A circuit implementing the logical OR operation on a number of qubits. | +| [`XOR`](qiskit.circuit.library.XOR "qiskit.circuit.library.XOR")(num\_qubits\[, amount, seed]) | An n\_qubit circuit for bitwise xor-ing the input with some integer `amount`. | +| [`InnerProduct`](qiskit.circuit.library.InnerProduct "qiskit.circuit.library.InnerProduct")(num\_qubits) | A 2n-qubit Boolean function that computes the inner product of two n-qubit vectors over $F_2$. | + +## Basis Change Circuits + +These circuits allow basis transformations of the qubit states. For example, in the case of the Quantum Fourier Transform (QFT), it transforms between the computational basis and the Fourier basis. + +| | | +| ------------------------------------------------------------------------------------------------------------ | ---------------------------------- | +| [`QFT`](qiskit.circuit.library.QFT "qiskit.circuit.library.QFT")(\[num\_qubits, approximation\_degree, ...]) | Quantum Fourier Transform Circuit. | + +## Arithmetic Circuits + +These [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")s perform classical arithmetic, such as addition or multiplication. + +### Amplitude Functions + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| [`LinearAmplitudeFunction`](qiskit.circuit.library.LinearAmplitudeFunction "qiskit.circuit.library.LinearAmplitudeFunction")(num\_state\_qubits, ...) | A circuit implementing a (piecewise) linear function on qubit amplitudes. | + +### Functional Pauli Rotations + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.FunctionalPauliRotations")(\[num\_state\_qubits, ...]) | Base class for functional Pauli rotations. | +| [`LinearPauliRotations`](qiskit.circuit.library.LinearPauliRotations "qiskit.circuit.library.LinearPauliRotations")(\[num\_state\_qubits, ...]) | Linearly-controlled X, Y or Z rotation. | +| [`PolynomialPauliRotations`](qiskit.circuit.library.PolynomialPauliRotations "qiskit.circuit.library.PolynomialPauliRotations")(\[num\_state\_qubits, ...]) | A circuit implementing polynomial Pauli rotations. | +| [`PiecewiseLinearPauliRotations`](qiskit.circuit.library.PiecewiseLinearPauliRotations "qiskit.circuit.library.PiecewiseLinearPauliRotations")(\[...]) | Piecewise-linearly-controlled Pauli rotations. | +| [`PiecewisePolynomialPauliRotations`](qiskit.circuit.library.PiecewisePolynomialPauliRotations "qiskit.circuit.library.PiecewisePolynomialPauliRotations")(\[...]) | Piecewise-polynomially-controlled Pauli rotations. | +| [`PiecewiseChebyshev`](qiskit.circuit.library.PiecewiseChebyshev "qiskit.circuit.library.PiecewiseChebyshev")(f\_x\[, degree, ...]) | Piecewise Chebyshev approximation to an input function. | + +### Adders + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [`DraperQFTAdder`](qiskit.circuit.library.DraperQFTAdder "qiskit.circuit.library.DraperQFTAdder")(num\_state\_qubits\[, kind, name]) | A circuit that uses QFT to perform in-place addition on two qubit registers. | +| [`CDKMRippleCarryAdder`](qiskit.circuit.library.CDKMRippleCarryAdder "qiskit.circuit.library.CDKMRippleCarryAdder")(num\_state\_qubits\[, ...]) | A ripple-carry circuit to perform in-place addition on two qubit registers. | +| [`VBERippleCarryAdder`](qiskit.circuit.library.VBERippleCarryAdder "qiskit.circuit.library.VBERippleCarryAdder")(num\_state\_qubits\[, ...]) | The VBE ripple carry adder \[1]. | +| [`WeightedAdder`](qiskit.circuit.library.WeightedAdder "qiskit.circuit.library.WeightedAdder")(\[num\_state\_qubits, weights, name]) | A circuit to compute the weighted sum of qubit registers. | + +### Multipliers + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| [`HRSCumulativeMultiplier`](qiskit.circuit.library.HRSCumulativeMultiplier "qiskit.circuit.library.HRSCumulativeMultiplier")(num\_state\_qubits\[, ...]) | A multiplication circuit to store product of two input registers out-of-place. | +| [`RGQFTMultiplier`](qiskit.circuit.library.RGQFTMultiplier "qiskit.circuit.library.RGQFTMultiplier")(num\_state\_qubits\[, ...]) | A QFT multiplication circuit to store product of two input registers out-of-place. | + +### Comparators + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | +| [`IntegerComparator`](qiskit.circuit.library.IntegerComparator "qiskit.circuit.library.IntegerComparator")(\[num\_state\_qubits, value, ...]) | Integer Comparator. | + +### Functions on binary variables + +| | | +| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| [`QuadraticForm`](qiskit.circuit.library.QuadraticForm "qiskit.circuit.library.QuadraticForm")(\[num\_result\_qubits, ...]) | Implements a quadratic form on binary variables encoded in qubit registers. | + +### Other arithmetic functions + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | +| [`ExactReciprocal`](qiskit.circuit.library.ExactReciprocal "qiskit.circuit.library.ExactReciprocal")(num\_state\_qubits, scaling\[, ...]) | Exact reciprocal | + +## Particular Quantum Circuits + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| [`FourierChecking`](qiskit.circuit.library.FourierChecking "qiskit.circuit.library.FourierChecking")(f, g) | Fourier checking circuit. | +| [`GraphState`](qiskit.circuit.library.GraphState "qiskit.circuit.library.GraphState")(adjacency\_matrix) | Circuit to prepare a graph state. | +| [`HiddenLinearFunction`](qiskit.circuit.library.HiddenLinearFunction "qiskit.circuit.library.HiddenLinearFunction")(adjacency\_matrix) | Circuit to solve the hidden linear function problem. | +| [`IQP`](qiskit.circuit.library.IQP "qiskit.circuit.library.IQP")(interactions) | Instantaneous quantum polynomial (IQP) circuit. | +| [`QuantumVolume`](qiskit.circuit.library.QuantumVolume "qiskit.circuit.library.QuantumVolume")(num\_qubits\[, depth, seed, ...]) | A quantum volume model circuit. | +| [`PhaseEstimation`](qiskit.circuit.library.PhaseEstimation "qiskit.circuit.library.PhaseEstimation")(num\_evaluation\_qubits, unitary) | Phase Estimation circuit. | +| [`GroverOperator`](qiskit.circuit.library.GroverOperator "qiskit.circuit.library.GroverOperator")(oracle\[, state\_preparation, ...]) | The Grover operator. | +| [`PhaseOracle`](qiskit.circuit.library.PhaseOracle "qiskit.circuit.library.PhaseOracle")(expression\[, synthesizer, var\_order]) | Phase Oracle. | +| [`EvolvedOperatorAnsatz`](qiskit.circuit.library.EvolvedOperatorAnsatz "qiskit.circuit.library.EvolvedOperatorAnsatz")(\[operators, reps, ...]) | The evolved operator ansatz. | +| [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")(operator\[, time, label, ...]) | Time-evolution of an operator consisting of Paulis. | +| [`HamiltonianGate`](qiskit.circuit.library.HamiltonianGate "qiskit.circuit.library.HamiltonianGate")(data, time\[, label]) | Class for representing evolution by a Hamiltonian operator as a gate. | +| [`UnitaryOverlap`](qiskit.circuit.library.UnitaryOverlap "qiskit.circuit.library.UnitaryOverlap")(unitary1, unitary2\[, ...]) | Circuit that returns the overlap between two unitaries $U_2^{\dag} U_1$. | + +## N-local circuits + +These `BlueprintCircuit` subclasses are used as parameterized models (a.k.a. ansatzes or variational forms) in variational algorithms. They are heavily used in near-term algorithms in e.g. Chemistry, Physics or Optimization. + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.NLocal")(\[num\_qubits, rotation\_blocks, ...]) | The n-local circuit class. | +| [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.TwoLocal")(\[num\_qubits, rotation\_blocks, ...]) | The two-local circuit. | +| [`PauliTwoDesign`](qiskit.circuit.library.PauliTwoDesign "qiskit.circuit.library.PauliTwoDesign")(\[num\_qubits, reps, seed, ...]) | The Pauli Two-Design ansatz. | +| [`RealAmplitudes`](qiskit.circuit.library.RealAmplitudes "qiskit.circuit.library.RealAmplitudes")(\[num\_qubits, entanglement, ...]) | The real-amplitudes 2-local circuit. | +| [`EfficientSU2`](qiskit.circuit.library.EfficientSU2 "qiskit.circuit.library.EfficientSU2")(\[num\_qubits, su2\_gates, ...]) | The hardware efficient SU(2) 2-local circuit. | +| [`ExcitationPreserving`](qiskit.circuit.library.ExcitationPreserving "qiskit.circuit.library.ExcitationPreserving")(\[num\_qubits, mode, ...]) | The heuristic excitation-preserving wave function ansatz. | +| [`QAOAAnsatz`](qiskit.circuit.library.QAOAAnsatz "qiskit.circuit.library.QAOAAnsatz")(\[cost\_operator, reps, ...]) | A generalized QAOA quantum circuit with a support of custom initial states and mixers. | + +## Data encoding circuits + +These `BlueprintCircuit` encode classical data in quantum states and are used as feature maps for classification. + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.PauliFeatureMap")(\[feature\_dimension, reps, ...]) | The Pauli Expansion circuit. | +| [`ZFeatureMap`](qiskit.circuit.library.ZFeatureMap "qiskit.circuit.library.ZFeatureMap")(feature\_dimension\[, reps, ...]) | The first order Pauli Z-evolution circuit. | +| [`ZZFeatureMap`](qiskit.circuit.library.ZZFeatureMap "qiskit.circuit.library.ZZFeatureMap")(feature\_dimension\[, reps, ...]) | Second-order Pauli-Z evolution circuit. | +| [`StatePreparation`](qiskit.circuit.library.StatePreparation "qiskit.circuit.library.StatePreparation")(params\[, num\_qubits, ...]) | Complex amplitude state preparation. | +| [`Initialize`](qiskit.circuit.library.Initialize "qiskit.circuit.library.Initialize")(params\[, num\_qubits, normalize]) | Complex amplitude initialization. | + +## Template circuits + +Templates are functions that return circuits that compute the identity. They are used at circuit optimization where matching part of the template allows the compiler to replace the match with the inverse of the remainder from the template. + +In this example, the identity constant in a template is checked: + +```python +from qiskit.circuit.library.templates import template_nct_4b_1 +from qiskit.quantum_info import Operator +import numpy as np + +template = template_nct_4b_1() + +identity = np.identity(2 ** len(template.qubits), dtype=complex) +data = Operator(template).data +np.allclose(data, identity) # True, template_nct_4b_1 is the identity +``` + +### NCT (Not-CNOT-Toffoli) template circuits + +Template circuits for [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"), [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"), and [`CCXGate`](qiskit.circuit.library.CCXGate "qiskit.circuit.library.CCXGate") (Toffoli) gates. + +**Reference:** Maslov, D. and Dueck, G. W. and Miller, D. M., Techniques for the synthesis of reversible Toffoli networks, 2007 [http://dx.doi.org/10.1145/1278349.1278355](http://dx.doi.org/10.1145/1278349.1278355) + +### template\_nct\_2a\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_2a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_2a_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_2a\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_2a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_2a_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_2a\_3 + + + +`qiskit.circuit.library.templates.nct.template_nct_2a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_2a_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_4a\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_4a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_4a_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_4a\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_4a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_4a_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_4a\_3 + + + +`qiskit.circuit.library.templates.nct.template_nct_4a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_4a_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_4b\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_4b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_4b_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_4b\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_4b_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_4b_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_5a\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_5a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_5a_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_5a\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_5a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_5a_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_5a\_3 + + + +`qiskit.circuit.library.templates.nct.template_nct_5a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_5a_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_5a\_4 + + + +`qiskit.circuit.library.templates.nct.template_nct_5a_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_5a_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6a\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_6a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6a_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6a\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_6a_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6a_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6a\_3 + + + +`qiskit.circuit.library.templates.nct.template_nct_6a_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6a_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6a\_4 + + + +`qiskit.circuit.library.templates.nct.template_nct_6a_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6a_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6b\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_6b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6b_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6b\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_6b_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6b_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_6c\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_6c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_6c_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_7a\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_7a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_7a_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_7b\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_7b_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_7b_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_7c\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_7c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_7c_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_7d\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_7d_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_7d_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_7e\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_7e_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_7e_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9a\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_9a_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9a_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_3 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_4 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_5 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_5()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_5.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_6 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_6()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_6.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_7 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_7()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_7.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_8 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_8()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_8.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_9 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_9()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_9.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_10 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_10()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_10.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_11 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_11()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_11.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9c\_12 + + + +`qiskit.circuit.library.templates.nct.template_nct_9c_12()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9c_12.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_1 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_2 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_3 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_4 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_5 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_5()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_5.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_6 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_6()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_6.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_7 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_7()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_7.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_8 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_8()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_8.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_9 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_9()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_9.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### template\_nct\_9d\_10 + + + +`qiskit.circuit.library.templates.nct.template_nct_9d_10()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/nct/template_nct_9d_10.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### Clifford template circuits + +Template circuits over Clifford gates. + +### clifford\_2\_1 + + + +`qiskit.circuit.library.clifford_2_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_2_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_2\_2 + + + +`qiskit.circuit.library.clifford_2_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_2_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_2\_3 + + + +`qiskit.circuit.library.clifford_2_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_2_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_2\_4 + + + +`qiskit.circuit.library.clifford_2_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_2_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_3\_1 + + + +`qiskit.circuit.library.clifford_3_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_3_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_4\_1 + + + +`qiskit.circuit.library.clifford_4_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_4_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_4\_2 + + + +`qiskit.circuit.library.clifford_4_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_4_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_4\_3 + + + +`qiskit.circuit.library.clifford_4_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_4_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_4\_4 + + + +`qiskit.circuit.library.clifford_4_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_4_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_5\_1 + + + +`qiskit.circuit.library.clifford_5_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_5_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_6\_1 + + + +`qiskit.circuit.library.clifford_6_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_6_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_6\_2 + + + +`qiskit.circuit.library.clifford_6_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_6_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_6\_3 + + + +`qiskit.circuit.library.clifford_6_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_6_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_6\_4 + + + +`qiskit.circuit.library.clifford_6_4()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_6_4.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_6\_5 + + + +`qiskit.circuit.library.clifford_6_5()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_6_5.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_8\_1 + + + +`qiskit.circuit.library.clifford_8_1()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_8_1.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_8\_2 + + + +`qiskit.circuit.library.clifford_8_2()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_8_2.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### clifford\_8\_3 + + + +`qiskit.circuit.library.clifford_8_3()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/clifford/clifford_8_3.py "view source code") + +**Returns** + +template as a quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### RZXGate template circuits + +Template circuits with [`RZXGate`](qiskit.circuit.library.RZXGate "qiskit.circuit.library.RZXGate"). + +### rzx\_yz + + + +`qiskit.circuit.library.rzx_yz(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/rzx/rzx_yz.py "view source code") + +Template for CX - RYGate - CX. + +### rzx\_xz + + + +`qiskit.circuit.library.rzx_xz(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/rzx/rzx_xz.py "view source code") + +Template for CX - RXGate - CX. + +### rzx\_cy + + + +`qiskit.circuit.library.rzx_cy(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/rzx/rzx_cy.py "view source code") + +Template for CX - RYGate - CX. + +### rzx\_zz1 + + + +`qiskit.circuit.library.rzx_zz1(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/rzx/rzx_zz1.py "view source code") + +Template for CX - RZGate - CX. + +### rzx\_zz2 + + + +`qiskit.circuit.library.rzx_zz2(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/rzx/rzx_zz2.py "view source code") + +Template for CX - RZGate - CX. + +### rzx\_zz3 + + + +`qiskit.circuit.library.rzx_zz3(theta=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/templates/rzx/rzx_zz3.py "view source code") + +Template for CX - RZGate - CX. + diff --git a/docs/api/qiskit/0.46/circuit_singleton.md b/docs/api/qiskit/0.46/circuit_singleton.md new file mode 100644 index 00000000000..cd7dceddb72 --- /dev/null +++ b/docs/api/qiskit/0.46/circuit_singleton.md @@ -0,0 +1,210 @@ +--- +title: singleton +description: API reference for qiskit.circuit.singleton +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.circuit.singleton +--- + + + + + + + +# Singleton instructions + + + +`qiskit.circuit.singleton` + +The machinery in this module is for defining subclasses of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") and [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") that preferentially return a shared immutable singleton instance when instantiated. Taking the example of [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"), the final user-facing result is that: + +* There is a regular class called `XGate`, which derives from [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"). +* Doing something like `XGate(label="my_gate")` produces an object whose type is exactly `XGate`, and all the mutability works completely as expected; all the methods resolve to exactly those defined by [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"), [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"), or parents. +* Doing `XGate()` produces a singleton object whose type is a synthetic `_SingletonXGate` class, which derives [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") but overrides [`__setattr__()`](https://docs.python.org/3/reference/datamodel.html#object.__setattr__ "(in Python v3.12)") to make itself immutable. The object itself has precisely the same instance attributes as `XGate()` would have if there was no singleton handling. This object will return itself under [`copy()`](https://docs.python.org/3/library/copy.html#copy.copy "(in Python v3.12)"), [`deepcopy()`](https://docs.python.org/3/library/copy.html#copy.deepcopy "(in Python v3.12)") and roundtrip through [`pickle`](https://docs.python.org/3/library/pickle.html#module-pickle "(in Python v3.12)"). + +The same can be true for, for example, [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure"), except that it’s a subclass of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") only, and not [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"). + + + The classes in this module are for advanced use, because they are closely entwined with the heart of Qiskit’s data model for circuits. + + +From a library-author perspective, the minimum that is needed to enhance a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") or [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") with this behaviour is to inherit from [`SingletonGate`](#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") ([`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction")) instead of [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") ([`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction")), and for the `__init__` method to have defaults for all of its arguments (these will be the state of the singleton instance). For example: + +```python +class XGate(SingletonGate): + def __init__(self, label=None): + super().__init__("x", 1, [], label=label) + +assert XGate() is XGate() +``` + +## Interface + +The public classes correspond to the standard classes [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") and [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"), respectively, and are subclasses of these. + + + +`qiskit.circuit.singleton.SingletonInstruction(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/singleton.py "view source code") + +A base class to use for [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") objects that by default are singleton instances. + +This class should be used for instruction classes that have fixed definitions and do not contain any unique state. The canonical example of something like this is [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure") which has an immutable definition and any instance of [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure") is the same. Using singleton instructions as a base class for these types of gate classes provides a large advantage in the memory footprint of multiple instructions. + +The exception to be aware of with this class though are the [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") attributes [`label`](qiskit.circuit.Instruction#label "qiskit.circuit.Instruction.label"), [`condition`](qiskit.circuit.Instruction#condition "qiskit.circuit.Instruction.condition"), [`duration`](qiskit.circuit.Instruction#duration "qiskit.circuit.Instruction.duration"), and [`unit`](qiskit.circuit.Instruction#unit "qiskit.circuit.Instruction.unit") which can be set differently for specific instances of gates. For [`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction") usage to be sound setting these attributes is not available and they can only be set at creation time, or on an object that has been specifically made mutable using [`to_mutable()`](qiskit.circuit.Instruction#to_mutable "qiskit.circuit.Instruction.to_mutable"). If any of these attributes are used during creation, then instead of using a single shared global instance of the same gate a new separate instance will be created. + + + +`qiskit.circuit.singleton.SingletonGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/singleton.py "view source code") + +A base class to use for [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") objects that by default are singleton instances. + +This class is very similar to [`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction"), except implies unitary [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") semantics as well. The same caveats around setting attributes in that class apply here as well. + + + +`qiskit.circuit.singleton.SingletonControlledGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/singleton.py "view source code") + +A base class to use for [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") objects that by default are singleton instances + +This class is very similar to [`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction"), except implies unitary [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") semantics as well. The same caveats around setting attributes in that class apply here as well. + +When inheriting from one of these classes, the produced class will have an eagerly created singleton instance that will be returned whenever the class is constructed with arguments that have been defined to be singletons. Typically this will be the defaults. These instances are immutable; attempts to modify their properties will raise [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)"). + +*All* subclasses of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") have a [`mutable`](qiskit.circuit.Instruction#mutable "qiskit.circuit.Instruction.mutable") property. For most instructions this is `True`, while for the singleton instances it is `False`. One can use the [`to_mutable()`](qiskit.circuit.Instruction#to_mutable "qiskit.circuit.Instruction.to_mutable") method to get a version of the instruction that is owned and safe to mutate. + +The singleton instances are not exact instances of their base class; they are special subclasses that cannot construct new objects. This means that: + +```python +type(XGate()) is not XGate +``` + +You should not rely on [`type`](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") having an exact value; use [`isinstance()`](https://docs.python.org/3/library/functions.html#isinstance "(in Python v3.12)") instead for type checking. If you need to reliably retrieve the base class from an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"), see the [`Instruction.base_class`](qiskit.circuit.Instruction#base_class "qiskit.circuit.Instruction.base_class") attribute; singleton instances set this correctly. For most cases in using Qiskit, [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") is a more suitable determiner of what an instruction “means” in a circuit. + +### Deriving new singletons + +The simplest example of deriving a new singleton instruction is simply to inherit from the correct base and supply an [`__init__()`](https://docs.python.org/3/reference/datamodel.html#object.__init__ "(in Python v3.12)") method that has immutable defaults for any arguments. For example: + +```python +from qiskit.circuit.singleton import SingletonInstruction + +class MyInstruction(SingletonInstruction): + def __init__(self, label=None): + super().__init__("my_instruction", 1, 0, label=label) + +assert MyInstruction() is MyInstruction() +assert MyInstruction(label="some label") is not MyInstruction() +assert MyInstruction(label="some label").mutable +``` + +The singleton instance will use all the constructor’s defaults. + +You can also derive from an instruction that is itself a singleton. The singleton nature of the class will be inherited, though the singleton instances of the two classes will be different: + +```python +class MyOtherInstruction(MyInstruction): + pass + +assert MyOtherInstruction() is MyOtherInstruction() +assert MyOtherInstruction() is not MyInstruction() +``` + +If for some reason you want to derive from [`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction"), or one of the related or subclasses but *do not* want the default singleton instance to be created, such as if you are defining a new abstract base class, you can set the keyword argument `create_default_singleton=False` in the class definition: + +```python +class NotASingleton(SingletonInstruction, create_default_singleton=False): + def __init__(self): + return super().__init__("my_mutable", 1, 0, []) + +assert NotASingleton() is not NotASingleton() +``` + +If your constructor does not have defaults for all its arguments, you must set `create_default_singleton=False`. + +Subclasses of [`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction") and the other associated classes can control how their constructor’s arguments are interpreted, in order to help the singleton machinery return the singleton even in the case than an optional argument is explicitly set to its default. + +### \_singleton\_lookup\_key + + + +`static SingletonInstruction._singleton_lookup_key(*_args, **_kwargs)` + +Given the arguments to the constructor, return a key tuple that identifies the singleton instance to retrieve, or `None` if the arguments imply that a mutable object must be created. + +For performance, as a special case, this method will not be called if the class constructor was given zero arguments (e.g. the construction `XGate()` will not call this method, but `XGate(label=None)` will), and the default singleton will immediately be returned. + +This static method can (and probably should) be overridden by subclasses. The derived signature should match the class’s `__init__`; this method should then examine the arguments to determine whether it requires mutability, or what the cache key (if any) should be. + +The function should return either `None` or valid `dict` key (i.e. hashable and implements equality). Returning `None` means that the created instance must be mutable. No further singleton-based processing will be done, and the class creation will proceed as if there was no singleton handling. Otherwise, the returned key can be anything hashable and no special meaning is ascribed to it. Whenever this method returns the same key, the same singleton instance will be returned. We suggest that you use a tuple of the values of all arguments that can be set while maintaining the singleton nature. + +Only keys that match the default arguments or arguments given to `additional_singletons` at class-creation time will actually return singletons; other values will return a standard mutable instance. + + + The singleton machinery will handle an unhashable return from this function gracefully by returning a mutable instance. Subclasses should ensure that their key is hashable in the happy path, but they do not need to manually verify that the user-supplied arguments are hashable. For example, it’s safe to implement this as: + + ```python + @staticmethod + def _singleton_lookup_key(*args, **kwargs): + return None if kwargs else args + ``` + + even though a user might give some unhashable type as one of the `args`. + + +This is set by all Qiskit standard-library gates such that the `label` and similar keyword arguments are ignored in the key calculation if they are their defaults, or a mutable instance is returned if they are not. + +You can also specify other combinations of constructor arguments to produce singleton instances for, using the `additional_singletons` argument in the class definition. This takes an iterable of `(args, kwargs)` tuples, and will build singletons equivalent to `cls(*args, **kwargs)`. You do not need to handle the case of the default arguments with this. For example, given a class definition: + +```python +class MySingleton(SingletonGate, additional_singletons=[((2,), {"label": "two"})]): + def __init__(self, n=1, label=None): + super().__init__("my", n, [], label=label) + + @staticmethod + def _singleton_lookup_key(n=1, label=None): + return (n, label) +``` + +there will be two singleton instances instantiated. One corresponds to `n=1` and `label=None`, and the other to `n=2` and `label="two"`. Whenever `MySingleton` is constructed with arguments consistent with one of those two cases, the relevant singleton will be returned. For example: + +```python +assert MySingleton() is MySingleton(1, label=None) +assert MySingleton(2, "two") is MySingleton(n=2, label="two") +``` + +The case of the class being instantiated with zero arguments is handled specially to allow an absolute fast-path for inner-loop performance (although the general machinery is not desperately slow anyway). + +## Implementation + + + This section is primarily developer documentation for the code; none of the machinery described here is public, and it is not safe to inherit from any of it directly. + + +There are several moving parts to tackle here. The behaviour of having `XGate()` return some singleton object that is an (inexact) instance of [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") but *without* calling `__init__` requires us to override [`type.__call__`](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)"). This means that [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") must have a metaclass that defines `__call__` to return the singleton instance. + +Next, we need to ensure that there *is* a singleton instance for `XGate()` to return. This can be done dynamically on each call (i.e. check if the instance exists and create it if not), but since we also want that instance to be very special, it’s easier to hook in and create it during the definition of the `XGate` type object. This also has the advantage that we do not need to make the singleton object pickleable; we only need to specify where to retrieve it from during the unpickle, because the creation of the base type object will recreate the singleton. + +We want the singleton instance to: + +* be immutable; it should reject all attempts to mutate itself. +* have exactly the same state as an `XGate()` would have had if there was no singleton handling. + +We do this in a three-step procedure: + +1. Before creating any singletons, we separately define the overrides needed to make an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") and a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") immutable. This is `_SingletonInstructionOverrides` and the other `_*Overrides` classes. +2. While we are creating the `XGate` type object, we dynamically *also* create a subclass of it that has the immutable overrides in its method-resolution order in the correct place. These override the standard methods / properties that are defined on the mutable gate (we do not attempt to override any cases where the type object we are creating has extra inplace methods). +3. We can’t instantiate this new subclass, because when it calls `XGate.__init__`, it will attempt to set some attributes, and these will be rejected by immutability. Instead, we first create a completely regular `XGate` instance, and then we dynamically change its type to the singleton class, freezing it. + +We could do this entirely within the metaclass machinery, but that would require `XGate` to be defined as something like: + +```python +class XGate(Gate, metaclass=_SingletonMeta, overrides=_SingletonGateOverrides): ... +``` + +which is super inconvenient (or we’d have to have `_SingletonMeta` do a bunch of fragile introspection). Instead, we use the [`abc.ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)")/[`abc.ABCMeta`](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)") pattern of defining a concrete middle class ([`SingletonGate`](#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") in the [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") case) that sets the metaclass, selects the overrides to be applied, and has an [`__init_subclass__()`](https://docs.python.org/3/reference/datamodel.html#object.__init_subclass__ "(in Python v3.12)") that applies the singleton-subclass-creation steps above. The overrides are in separate classes so that *mutable* [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") instances do not have them in their own method-resolution orders; doing this is easier to implement, but requires all the setters and checkers to dance around at runtime trying to validate whether mutating the instance is allowed. + +Finally, to actually build all this machinery up, the base is `_SingletonMeta`, which is a metaclass compatible with any metaclass of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"). This defines the [`__call__()`](https://docs.python.org/3/reference/datamodel.html#object.__call__ "(in Python v3.12)") machinery that overrides [`type.__call__`](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") to return the singleton instances. The other component of it is its [`__new__()`](https://docs.python.org/3/reference/datamodel.html#object.__new__ "(in Python v3.12)"), which is called (non-trivially) during the creation of [`SingletonGate`](#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") and [`SingletonInstruction`](#qiskit.circuit.singleton.SingletonInstruction "qiskit.circuit.singleton.SingletonInstruction") with its `overrides` keyword argument set to define the `__init_subclass__` of those classes with the above properties. We use the metaclass to add this method dynamically, because the [`__init_subclass__()`](https://docs.python.org/3/reference/datamodel.html#object.__init_subclass__ "(in Python v3.12)") machinery wants to be abstract, closing over the `overrides` and the base class, but still able to call [`super`](https://docs.python.org/3/library/functions.html#super "(in Python v3.12)"). It’s more convenient to do this dynamically, closing over the desired class variable and using the two-argument form of [`super`](https://docs.python.org/3/library/functions.html#super "(in Python v3.12)"), since the zero-argument form does magic introspection based on where its containing function was defined. + +Handling multiple singletons requires storing the initialization arguments in some form, to allow the [`to_mutable()`](qiskit.circuit.Instruction#to_mutable "qiskit.circuit.Instruction.to_mutable") method and pickling to be defined. We do this as a lookup dictionary on the singleton *type object*. This is logically an instance attribute, but because we need to dynamically switch in the dynamic \_Singleton type onto an instance of the base type, that gets rather complex; either we have to require that the base already has an instance dictionary, or we risk breaking the `__slots__` layout during the switch. Since the singletons have lifetimes that last until garbage collection of their base class’s type object, we can fake out this instance dictionary using a type-object dictionary that maps instance pointers to the data we want to store. An alternative would be to build a new type object for each individual singleton that closes over (or stores) the initializer arguments, but type objects are quite heavy and the principle is largely same anyway. + diff --git a/docs/api/qiskit/0.46/classicalfunction.md b/docs/api/qiskit/0.46/classicalfunction.md new file mode 100644 index 00000000000..affc59df4fe --- /dev/null +++ b/docs/api/qiskit/0.46/classicalfunction.md @@ -0,0 +1,84 @@ +--- +title: classicalfunction +description: API reference for qiskit.circuit.classicalfunction +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.circuit.classicalfunction +--- + + + + + + + +# ClassicalFunction compiler + + + +`qiskit.circuit.classicalfunction` + +## Overview + +The classical function compiler provides the necessary tools to map a classical potentially irreversible functions into quantum circuits. Below is a simple example of how to synthesize a simple boolean function defined using Python into a QuantumCircuit: + +> ```python +> from qiskit.circuit.classicalfunction import classical_function +> from qiskit.circuit.classicalfunction.types import Int1 +> +> @classical_function +> def grover_oracle(a: Int1, b: Int1, c: Int1, d: Int1) -> Int1: +> return (not a and b and not c and d) +> +> quantum_circuit = grover_oracle.synth(registerless=False) +> quantum_circuit.draw('text') +> +> a: ──o── +> │ +> b: ──■── +> │ +> c: ──o── +> │ +> d: ──■── +> ┌─┴─┐ +> return: ┤ X ├ +> └───┘ +> ``` + +Following Qiskit’s little-endian bit ordering convention, the left-most bit (`a`) is the most significant bit and the right-most bit (`d`) is the least significant bit. + +## Supplementary Information + +### Tweedledum + +Tweedledum is a C++-17 header-only library that implements a large set of reversible (and quantum) synthesis, optimization, and mapping algorithms. The classical function compiler relies on it and its dependencies to both represent logic networks and synthesize them into quantum circuits. + +### ClassicalFunction data types + +At the moment, the only type supported by the classical\_function compilers is `qiskit.circuit.classicalfunction.types.Int1`. The classical function function to parse *must* include type hints (just `Int1` for now). The resulting gate will be a gate in the size of the sum of all the parameters and the return. + +The type `Int1` means the classical function will only operate at bit level. + +## ClassicalFunction compiler API + + + +### classical\_function + +Decorator for a classical function that returns a ClassicalFunction object. + +### ClassicalFunction + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| [`ClassicalFunction`](qiskit.circuit.classicalfunction.ClassicalFunction "qiskit.circuit.classicalfunction.ClassicalFunction")(source\[, name]) | Represent a classical function and its logic network. | +| [`BooleanExpression`](qiskit.circuit.classicalfunction.BooleanExpression "qiskit.circuit.classicalfunction.BooleanExpression")(expression\[, name, var\_order]) | The Boolean Expression gate. | + +### Exceptions + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| [`ClassicalFunctionCompilerTypeError`](qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError "qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError")(\*message) | ClassicalFunction compiler type error. | +| [`ClassicalFunctionParseError`](qiskit.circuit.classicalfunction.ClassicalFunctionParseError "qiskit.circuit.classicalfunction.ClassicalFunctionParseError")(\*message) | ClassicalFunction compiler parse error. | +| [`ClassicalFunctionCompilerTypeError`](qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError "qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError")(\*message) | ClassicalFunction compiler type error. | + diff --git a/docs/api/qiskit/0.46/compiler.md b/docs/api/qiskit/0.46/compiler.md new file mode 100644 index 00000000000..d4b64eb6edd --- /dev/null +++ b/docs/api/qiskit/0.46/compiler.md @@ -0,0 +1,310 @@ +--- +title: compiler +description: API reference for qiskit.compiler +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.compiler +--- + + + + + + + +# Compilation Routines + + + +`qiskit.compiler` + +## Circuit and Pulse Compilation Functions + +### assemble + + + +`qiskit.compiler.assemble(experiments, backend=None, qobj_id=None, qobj_header=None, shots=None, memory=False, seed_simulator=None, qubit_lo_freq=None, meas_lo_freq=None, qubit_lo_range=None, meas_lo_range=None, schedule_los=None, meas_level=MeasLevel.CLASSIFIED, meas_return=MeasReturnType.AVERAGE, meas_map=None, memory_slot_size=100, rep_time=None, rep_delay=None, parameter_binds=None, parametric_pulses=None, init_qubits=True, **run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/compiler/assembler.py "view source code") + +Assemble a list of circuits or pulse schedules into a `Qobj`. + +This function serializes the payloads, which could be either circuits or schedules, to create `Qobj` “experiments”. It further annotates the experiment payload with header and configurations. + +NOTE: Backend.options is not used within assemble. The required values (previously given by backend.set\_options) should be manually extracted from options and supplied directly when calling. + +**Parameters** + +* **experiments** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] |* [*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")*] |* [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")*]*) – Circuit(s) or pulse schedule(s) to execute + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – If set, some runtime options are automatically grabbed from `backend.configuration()` and `backend.defaults()`. If any other option is explicitly set (e.g., `rep_time`), it will override the backend’s. If any other options is set in the run\_config, it will also override the backend’s. + +* **qobj\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – String identifier to annotate the `Qobj` + +* **qobj\_header** ([*QobjHeader*](qiskit.qobj.QobjHeader "qiskit.qobj.common.QobjHeader") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)") *| None*) – User input that will be inserted in `Qobj` header, and will also be copied to the corresponding Result header. Headers do not affect the run. + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Number of repetitions of each circuit, for sampling. Default: 1024 or `max_shots` from the backend configuration, whichever is smaller + +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. + +* **seed\_simulator** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Random seed to control sampling, for when backend is a simulator + +* **qubit\_lo\_freq** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – List of job level qubit drive LO frequencies in Hz. Overridden by `schedule_los` if specified. Must have length `n_qubits.` + +* **meas\_lo\_freq** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – List of measurement LO frequencies in Hz. Overridden by `schedule_los` if specified. Must have length `n_qubits.` + +* **qubit\_lo\_range** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – List of job level drive LO ranges each of form `[range_min, range_max]` in Hz. Used to validate `qubit_lo_freq`. Must have length `n_qubits.` + +* **meas\_lo\_range** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – List of job level measurement LO ranges each of form `[range_min, range_max]` in Hz. Used to validate `meas_lo_freq`. Must have length `n_qubits.` + +* **schedule\_los** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[PulseChannel,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | LoConfig] |* [*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[PulseChannel,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | LoConfig | None*) – Experiment level (ie circuit or schedule) LO frequency configurations for qubit drive and measurement channels. These values override the job level values from `default_qubit_los` and `default_meas_los`. Frequencies are in Hz. Settable for OpenQASM 2 and pulse jobs. + +* **meas\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| MeasLevel*) – Set the appropriate level of the measurement output for pulse experiments. + +* **meas\_return** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| MeasReturnType*) – + + Level of measurement data for the backend to return. + + **For `meas_level` 0 and 1:** + + * `single` returns information from every shot. + * `avg` returns average measurement output (averaged over number of shots). + +* **meas\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit")*]] | None*) – List of lists, containing qubits that must be measured together. + +* **memory\_slot\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Size of each memory slot if the output is Level 0. + +* **rep\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time per program execution in seconds. Must be from the list provided by the backend (`backend.configuration().rep_times`). Defaults to the first entry. + +* **rep\_delay** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` will be used instead of `rep_time` and must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. + +* **parameter\_binds** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – List of Parameter bindings over which the set of experiments will be executed. Each list element (bind) should be of the form \{Parameter1: value1, Parameter2: value2, …}. All binds will be executed across all experiments; e.g., if parameter\_binds is a length-n list, and there are m experiments, a total of m x n experiments will be run (one for each experiment/bind pair). + +* **parametric\_pulses** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – + + A list of pulse shapes which are supported internally on the backend. Example: + + ```python + ['gaussian', 'constant'] + ``` + +* **init\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reset the qubits to the ground state for each shot. Default: `True`. + +* **\*\*run\_config** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")) – Extra arguments used to configure the run (e.g., for Aer configurable backends). Refer to the backend documentation for details on these arguments. + +**Returns** + +A `Qobj` that can be run on a backend. Depending on the type of input, this will be either a `QasmQobj` or a `PulseQobj`. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input cannot be interpreted as either circuits or schedules + +**Return type** + +[*QasmQobj*](qiskit.qobj.QasmQobj "qiskit.qobj.qasm_qobj.QasmQobj") | [*PulseQobj*](qiskit.qobj.PulseQobj "qiskit.qobj.pulse_qobj.PulseQobj") + +### schedule + + + +`qiskit.compiler.schedule(circuits, backend=None, inst_map=None, meas_map=None, dt=None, method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/compiler/scheduler.py "view source code") + +Schedule a circuit to a pulse `Schedule`, using the backend, according to any specified methods. Supported methods are documented in `qiskit.scheduler.schedule_circuit`. + +**Parameters** + +* **circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*]*) – The quantum circuit or circuits to translate +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – A backend instance, which contains hardware-specific data required for scheduling +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.instruction_schedule_map.InstructionScheduleMap") *| None*) – Mapping of circuit operations to pulse schedules. If `None`, defaults to the `backend`’s `instruction_schedule_map` +* **meas\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – List of sets of qubits that must be measured together. If `None`, defaults to the `backend`’s `meas_map` +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The output sample rate of backend control electronics. For scheduled circuits which contain time information, dt is required. If not provided, it will be obtained from the backend configuration +* **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – Optionally specify a particular scheduling method + +**Returns** + +A pulse `Schedule` that implements the input circuit + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If `inst_map` and `meas_map` are not passed and `backend` is not passed + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")] + +### transpile + + + +`qiskit.compiler.transpile(circuits, backend=None, basis_gates=None, inst_map=None, coupling_map=None, backend_properties=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, dt=None, approximation_degree=1.0, timing_constraints=None, seed_transpiler=None, optimization_level=None, callback=None, output_name=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None, ignore_backend_supplied_default_methods=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/compiler/transpiler.py "view source code") + +Transpile one or more circuits, according to some desired transpilation targets. + +Transpilation is potentially done in parallel using multiprocessing when `circuits` is a list with > 1 [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object depending on the local environment and configuration. + +**Parameters** + +* **circuits** (*\_CircuitT*) – Circuit(s) to transpile + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – If set, the transpiler will compile the input circuit to this target device. If any other option is explicitly set (e.g., `coupling_map`), it will override the backend’s. + +* **basis\_gates** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – List of basis gate names to unroll to (e.g: `['u1', 'u2', 'u3', 'cx']`). If `None`, do not unroll. + +* **inst\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.instruction_schedule_map.InstructionScheduleMap")*] | None*) – Mapping of unrolled gates to pulse schedules. If this is not provided, transpiler tries to get from the backend. If any user defined calibration is found in the map and this is used in a circuit, transpiler attaches the custom gate definition to the circuit. This enables one to flexibly override the low-level instruction implementation. This feature is available iff the backend supports the pulse gate experiment. + +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – + + Directed coupling map (perhaps custom) to target in mapping. If the coupling map is symmetric, both directions need to be specified. + + Multiple formats are supported: + + 1. `CouplingMap` instance + 2. List, must be given as an adjacency matrix, where each entry specifies all directed two-qubit interactions supported by backend, e.g: `[[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]` + +* **backend\_properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.backendproperties.BackendProperties") *| None*) – properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. Find a backend that provides this information with: `backend.properties()` + +* **initial\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)") *| None*) – + + Initial position of virtual qubits on physical qubits. If this layout makes the circuit compatible with the coupling\_map constraints, it will be used. The final layout is not guaranteed to be the same, as the transpiler may permute qubits through swaps or other means. Multiple formats are supported: + + 1. `Layout` instance + + 2. Dict \* virtual to physical: + + ```python + {qr[0]: 0, + qr[1]: 3, + qr[2]: 5} + ``` + + * physical to virtual: + + ```python + {0: qr[0], + 3: qr[1], + 5: qr[2]} + ``` + + 3. List + + * virtual to physical: + + ```python + [0, 3, 5] # virtual qubits are ordered (in addition to named) + ``` + + * physical to virtual: + + ```python + [qr[0], None, None, qr[1], None, qr[2]] + ``` + +* **layout\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of layout selection pass (‘trivial’, ‘dense’, ‘noise\_adaptive’, ‘sabre’). This can also be the external plugin name to use for the `layout` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"layout"` for the `stage_name` argument. + +* **routing\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of routing pass (‘basic’, ‘lookahead’, ‘stochastic’, ‘sabre’, ‘none’). Note This can also be the external plugin name to use for the `routing` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"routing"` for the `stage_name` argument. + +* **translation\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of translation pass (‘unroller’, ‘translator’, ‘synthesis’) This can also be the external plugin name to use for the `translation` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"translation"` for the `stage_name` argument. + +* **scheduling\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of scheduling pass. \* `'as_soon_as_possible'`: Schedule instructions greedily, as early as possible on a qubit resource. (alias: `'asap'`) \* `'as_late_as_possible'`: Schedule instructions late, i.e. keeping qubits in the ground state when possible. (alias: `'alap'`) If `None`, no scheduling will be done. This can also be the external plugin name to use for the `scheduling` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"scheduling"` for the `stage_name` argument. + +* **instruction\_durations** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None]] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] |* [*InstructionDurations*](qiskit.transpiler.InstructionDurations "qiskit.transpiler.instruction_durations.InstructionDurations") *| None*) – Durations of instructions. Applicable only if scheduling\_method is specified. The gate lengths defined in `backend.properties` are used as default. They are overwritten if this `instruction_durations` is specified. The format of `instruction_durations` must be as follows. The instruction\_durations must be given as a list of tuples \[(instruction\_name, qubits, duration, unit), …]. | \[(‘cx’, \[0, 1], 12.3, ‘ns’), (‘u3’, \[0], 4.56, ‘ns’)] | \[(‘cx’, \[0, 1], 1000), (‘u3’, \[0], 300)] If unit is omitted, the default is ‘dt’, which is a sample time depending on backend. If the time unit is ‘dt’, the duration must be an integer. + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Backend sample time (resolution) in seconds. If `None` (default), `backend.configuration().dt` is used. + +* **approximation\_degree** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation) + +* **timing\_constraints** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – + + An optional control hardware restriction on instruction time resolution. A quantum computer backend may report a set of restrictions, namely: + + * granularity: An integer value representing minimum pulse gate resolution in units of `dt`. A user-defined pulse gate should have duration of a multiple of this granularity value. + * min\_length: An integer value representing minimum pulse gate length in units of `dt`. A user-defined pulse gate should be longer than this length. + * pulse\_alignment: An integer value representing a time resolution of gate instruction starting time. Gate instruction should start at time which is a multiple of the alignment value. + * acquire\_alignment: An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at time which is a multiple of the alignment value. + + This information will be provided by the backend configuration. If the backend doesn’t have any restriction on the instruction time allocation, then `timing_constraints` is None and no adjustment will be performed. + +* **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Sets random seed for the stochastic parts of the transpiler + +* **optimization\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – + + How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time. + + * 0: no optimization + * 1: light optimization + * 2: heavy optimization + * 3: even heavier optimization + + If `None`, level 1 will be chosen as default. + +* **callback** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[BasePass,* [*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*PropertySet*](qiskit.passmanager.PropertySet "qiskit.passmanager.compilation_status.PropertySet")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – + + A callback function that will be called after each pass execution. The function will be called with 5 keyword arguments, | `pass_`: the pass being run. | `dag`: the dag output of the pass. | `time`: the time to execute the pass. | `property_set`: the property set. | `count`: the index for the pass execution. The exact arguments passed expose the internals of the pass manager, and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases, be sure to check that the arguments being passed are the same. To use the callback feature, define a function that will take in kwargs dict and access the variables. For example: + + ```python + def callback_func(**kwargs): + pass_ = kwargs['pass_'] + dag = kwargs['dag'] + time = kwargs['time'] + property_set = kwargs['property_set'] + count = kwargs['count'] + ... + transpile(circ, callback=callback_func) + ``` + +* **output\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – A list with strings to identify the output circuits. The length of the list should be exactly the length of the `circuits` parameter. + +* **unitary\_synthesis\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the unitary synthesis method to use. By default `'default'` is used. You can see a list of installed plugins with [`unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names"). + +* **unitary\_synthesis\_plugin\_config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – An optional configuration dictionary that will be passed directly to the unitary synthesis plugin. By default this setting will have no effect as the default unitary synthesis method does not take custom configuration. This should only be necessary when a unitary synthesis plugin is specified with the `unitary_synthesis` argument. As this is custom for each unitary synthesis plugin refer to the plugin documentation for how to use this option. + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.target.Target") *| None*) – A backend transpiler target. Normally this is specified as part of the `backend` argument, but if you have manually constructed a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object you can specify it manually here. This will override the target from `backend`. + +* **hls\_config** (*HLSConfig | None*) – An optional configuration class `HLSConfig` that will be passed directly to `HighLevelSynthesis` transformation pass. This configuration class allows to specify for various high-level objects the lists of synthesis algorithms and their parameters. + +* **init\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The plugin name to use for the `init` stage. By default an external plugin is not used. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"init"` for the stage name argument. + +* **optimization\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The plugin name to use for the `optimization` stage. By default an external plugin is not used. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"optimization"` for the `stage_name` argument. + +* **ignore\_backend\_supplied\_default\_methods** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` any default methods specified by a backend will be ignored. Some backends specify alternative default methods to support custom compilation target-specific passes/plugins which support backend-specific compilation techniques. If you’d prefer that these defaults were not used this option is used to disable those backend-specific defaults. + +**Returns** + +The transpiled circuit(s). + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – in case of bad inputs to transpiler (like conflicting parameters) or errors in passes + +**Return type** + +*\_CircuitT* + +### sequence + + + +`qiskit.compiler.sequence(scheduled_circuits, backend=None, inst_map=None, meas_map=None, dt=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/compiler/sequencer.py "view source code") + +Schedule a scheduled circuit to a pulse `Schedule`, using the backend. + +**Parameters** + +* **scheduled\_circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*]*) – Scheduled circuit(s) to be translated +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – A backend instance, which contains hardware-specific data required for scheduling +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.instruction_schedule_map.InstructionScheduleMap") *| None*) – Mapping of circuit operations to pulse schedules. If `None`, defaults to the `backend`’s `instruction_schedule_map` +* **meas\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – List of sets of qubits that must be measured together. If `None`, defaults to the `backend`’s `meas_map` +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The output sample rate of backend control electronics. For scheduled circuits which contain time information, dt is required. If not provided, it will be obtained from the backend configuration + +**Returns** + +A pulse `Schedule` that implements the input circuit + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If `inst_map` and `meas_map` are not passed and `backend` is not passed + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")] + diff --git a/docs/api/qiskit/0.46/converters.md b/docs/api/qiskit/0.46/converters.md new file mode 100644 index 00000000000..bf6bd7e0ff7 --- /dev/null +++ b/docs/api/qiskit/0.46/converters.md @@ -0,0 +1,310 @@ +--- +title: converters +description: API reference for qiskit.converters +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.converters +--- + + + + + + + +# Circuit Converters + + + +`qiskit.converters` + +### circuit\_to\_dag + + + +`qiskit.converters.circuit_to_dag(circuit, copy_operations=True, *, qubit_order=None, clbit_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/circuit_to_dag.py "view source code") + +Build a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit. +* **copy\_operations** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Deep copy the operation objects in the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") for the output [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit"). This should only be set to `False` if the input [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") will not be used anymore as the operations in the output [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") will be shared instances and modifications to operations in the [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") will be reflected in the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") (and vice versa). +* **qubit\_order** (*Iterable\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*] or None*) – the order that the qubits should be indexed in the output DAG. Defaults to the same order as in the circuit. +* **clbit\_order** (*Iterable\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*] or None*) – the order that the clbits should be indexed in the output DAG. Defaults to the same order as in the circuit. + +**Returns** + +the DAG representing the input circuit. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if the `qubit_order` or `clbit_order` parameters do not match the bits in the circuit. + +**Example** + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.dagcircuit import DAGCircuit +from qiskit.converters import circuit_to_dag + +q = QuantumRegister(3, 'q') +c = ClassicalRegister(3, 'c') +circ = QuantumCircuit(q, c) +circ.h(q[0]) +circ.cx(q[0], q[1]) +circ.measure(q[0], c[0]) +circ.rz(0.5, q[1]).c_if(c, 2) +dag = circuit_to_dag(circ) +``` + +### dag\_to\_circuit + + + +`qiskit.converters.dag_to_circuit(dag, copy_operations=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/dag_to_circuit.py "view source code") + +Build a `QuantumCircuit` object from a `DAGCircuit`. + +**Parameters** + +* **dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the input dag. +* **copy\_operations** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Deep copy the operation objects in the [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") for the output [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). This should only be set to `False` if the input [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") will not be used anymore as the operations in the output [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") will be shared instances and modifications to operations in the [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") will be reflected in the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") (and vice versa). + +**Returns** + +the circuit representing the input dag. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Example** + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.dagcircuit import DAGCircuit +from qiskit.converters import circuit_to_dag +from qiskit.circuit.library.standard_gates import CHGate, U2Gate, CXGate +from qiskit.converters import dag_to_circuit + +q = QuantumRegister(3, 'q') +c = ClassicalRegister(3, 'c') +circ = QuantumCircuit(q, c) +circ.h(q[0]) +circ.cx(q[0], q[1]) +circ.measure(q[0], c[0]) +circ.rz(0.5, q[1]).c_if(c, 2) +dag = circuit_to_dag(circ) +circuit = dag_to_circuit(dag) +circuit.draw('mpl') +``` + +![../\_images/converters-1.png](/images/api/qiskit/0.46/converters-1.png) + +### circuit\_to\_instruction + + + +`qiskit.converters.circuit_to_instruction(circuit, parameter_map=None, equivalence_library=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/circuit_to_instruction.py "view source code") + +Build an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +The instruction is anonymous (not tied to a named quantum register), and so can be inserted into another circuit. The instruction will have the same string name as the circuit. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit. +* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the instruction. If None, existing circuit parameters will also parameterize the instruction. +* **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – Optional equivalence library where the converted instruction will be registered. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional instruction label. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if parameter\_map is not compatible with circuit + +**Returns** + +an instruction equivalent to the action of the input circuit. Upon decomposition, this instruction will yield the components comprising the original circuit. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Example** + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.converters import circuit_to_instruction + +q = QuantumRegister(3, 'q') +c = ClassicalRegister(3, 'c') +circ = QuantumCircuit(q, c) +circ.h(q[0]) +circ.cx(q[0], q[1]) +circ.measure(q[0], c[0]) +circ.rz(0.5, q[1]).c_if(c, 2) +circuit_to_instruction(circ) +``` + +### circuit\_to\_gate + + + +`qiskit.converters.circuit_to_gate(circuit, parameter_map=None, equivalence_library=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/circuit_to_gate.py "view source code") + +Build a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +The gate is anonymous (not tied to a named quantum register), and so can be inserted into another circuit. The gate will have the same string name as the circuit. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit. +* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the gate. If None, existing circuit parameters will also parameterize the Gate. +* **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – Optional equivalence library where the converted gate will be registered. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional gate label. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if circuit is non-unitary or if parameter\_map is not compatible with circuit + +**Returns** + +a Gate equivalent to the action of the input circuit. Upon decomposition, this gate will yield the components comprising the original circuit. + +**Return type** + +[Gate](qiskit.circuit.Gate "qiskit.circuit.Gate") + +### ast\_to\_dag + + + +`qiskit.converters.ast_to_dag(ast)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/ast_to_dag.py "view source code") + +Build a `DAGCircuit` object from an AST `Node` object. + + + The function `qiskit.converters.ast_to_dag.ast_to_dag()` is deprecated as of qiskit 0.46. It will be removed in the 1.0.0 release. Instead use the qiskit.qasm2.dump() or qiskit.qasm2.dumps() function + + +**Parameters** + +**ast** (*Program*) – a Program Node of an AST (parser’s output) + +**Returns** + +the DAG representing an OpenQASM’s AST + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the AST is malformed. + +**Example** + +```python +from qiskit.converters import ast_to_dag +from qiskit import qasm, QuantumCircuit, ClassicalRegister, QuantumRegister + +q = QuantumRegister(3, 'q') +c = ClassicalRegister(3, 'c') +circ = QuantumCircuit(q, c) +circ.h(q[0]) +circ.cx(q[0], q[1]) +circ.measure(q[0], c[0]) +circ.rz(0.5, q[1]).c_if(c, 2) +qasm_str = circ.qasm() +ast = qasm.Qasm(data=qasm_str).parse() +dag = ast_to_dag(ast) +``` + +### dagdependency\_to\_circuit + + + +`qiskit.converters.dagdependency_to_circuit(dagdependency)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/dagdependency_to_circuit.py "view source code") + +Build a `QuantumCircuit` object from a `DAGDependency`. + +**Parameters** + +**dagdependency** ([*DAGDependency*](qiskit.dagcircuit.DAGDependency "qiskit.dagcircuit.DAGDependency")) – the input dag. + +**Returns** + +the circuit representing the input dag dependency. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### circuit\_to\_dagdependency + + + +`qiskit.converters.circuit_to_dagdependency(circuit, create_preds_and_succs=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/circuit_to_dagdependency.py "view source code") + +Build a `DAGDependency` object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the input circuit. +* **create\_preds\_and\_succs** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to construct lists of predecessors and successors for every node. + +**Returns** + +the DAG representing the input circuit as a dag dependency. + +**Return type** + +[DAGDependency](qiskit.dagcircuit.DAGDependency "qiskit.dagcircuit.DAGDependency") + +### dag\_to\_dagdependency + + + +`qiskit.converters.dag_to_dagdependency(dag, create_preds_and_succs=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/dag_to_dagdependency.py "view source code") + +Build a `DAGDependency` object from a `DAGCircuit`. + +**Parameters** + +* **dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the input dag. +* **create\_preds\_and\_succs** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to construct lists of predecessors and successors for every node. + +**Returns** + +the DAG representing the input circuit as a dag dependency. + +**Return type** + +[DAGDependency](qiskit.dagcircuit.DAGDependency "qiskit.dagcircuit.DAGDependency") + +### dagdependency\_to\_dag + + + +`qiskit.converters.dagdependency_to_dag(dagdependency)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/converters/dagdependency_to_dag.py "view source code") + +Build a `DAGCircuit` object from a `DAGDependency`. + +**Parameters** + +**dependency** (*dag*) – the input dag. + +**Returns** + +the DAG representing the input circuit. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + diff --git a/docs/api/qiskit/0.46/dagcircuit.md b/docs/api/qiskit/0.46/dagcircuit.md new file mode 100644 index 00000000000..1df38534736 --- /dev/null +++ b/docs/api/qiskit/0.46/dagcircuit.md @@ -0,0 +1,54 @@ +--- +title: dagcircuit +description: API reference for qiskit.dagcircuit +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.dagcircuit +--- + + + + + + + +# DAG Circuits + + + +`qiskit.dagcircuit` + +## Circuits as Directed Acyclic Graphs + +| | | +| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")() | Quantum circuit as a directed acyclic graph. | +| [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.DAGNode")(\[nid]) | Parent class for DAGOpNode, DAGInNode, and DAGOutNode. | +| [`DAGOpNode`](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")(op\[, qargs, cargs, dag]) | Object to represent an Instruction at a node in the DAGCircuit. | +| [`DAGInNode`](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")(wire) | Object to represent an incoming wire node in the DAGCircuit. | +| [`DAGOutNode`](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")(wire) | Object to represent an outgoing wire node in the DAGCircuit. | +| [`DAGDepNode`](qiskit.dagcircuit.DAGDepNode "qiskit.dagcircuit.DAGDepNode")(\[type, op, name, qargs, cargs, ...]) | Object to represent the information at a node in the DAGDependency(). | +| [`DAGDependency`](qiskit.dagcircuit.DAGDependency "qiskit.dagcircuit.DAGDependency")() | Object to represent a quantum circuit as a Directed Acyclic Graph (DAG) via operation dependencies (i.e. | + +## Exceptions + +### DAGCircuitError + + + +`qiskit.dagcircuit.DAGCircuitError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/exceptions.py "view source code") + +Base class for errors raised by the DAGCircuit object. + +Set the error message. + +### DAGDependencyError + + + +`qiskit.dagcircuit.DAGDependencyError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/exceptions.py "view source code") + +Base class for errors raised by the DAGDependency object. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/exceptions.md b/docs/api/qiskit/0.46/exceptions.md new file mode 100644 index 00000000000..983b3da06c8 --- /dev/null +++ b/docs/api/qiskit/0.46/exceptions.md @@ -0,0 +1,72 @@ +--- +title: exceptions +description: API reference for qiskit.exceptions +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.exceptions +--- + + + + + + + +# Top-level exceptions + + + +`qiskit.exceptions` + +All Qiskit-related errors raised by Qiskit are subclasses of the base: + +### QiskitError + + + +`qiskit.exceptions.QiskitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/exceptions.py "view source code") + +Base class for errors raised by Qiskit. + +Set the error message. + + + Errors that are just general programming errors, such as incorrect typing, may still raise standard Python errors such as `TypeError`. [`QiskitError`](#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") is generally for errors raised in usage that is particular to Qiskit. + + +Many of the Qiskit subpackages define their own more granular error, to help in catching only the subset of errors you care about. For example, [`qiskit.circuit`](circuit#module-qiskit.circuit "qiskit.circuit") almost exclusively uses [`CircuitError`](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError"), while both [`QASM2ExportError`](qasm2#qiskit.qasm2.QASM2ExportError "qiskit.qasm2.QASM2ExportError") and [`QASM2ParseError`](qasm2#qiskit.qasm2.QASM2ParseError "qiskit.qasm2.QASM2ParseError") derive from [`QASM2Error`](qasm2#qiskit.qasm2.QASM2Error "qiskit.qasm2.QASM2Error") in [`qiskit.qasm2`](qasm2#module-qiskit.qasm2 "qiskit.qasm2"), which is in turn a type of [`QiskitError`](#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError"). + +Qiskit has several optional features that depend on other packages that are not required for a minimal install. You can read more about those, and ways to check for their presence, in [`qiskit.utils.optionals`](utils#module-qiskit.utils.optionals "qiskit.utils.optionals"). Trying to use a feature that requires an optional extra will raise a particular error, which subclasses both [`QiskitError`](#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") and the Python built-in `ImportError`. + +### MissingOptionalLibraryError + + + +`qiskit.exceptions.MissingOptionalLibraryError(libname, name, pip_install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/exceptions.py "view source code") + +Raised when an optional library is missing. + +Set the error message. :param libname: Name of missing library :param name: Name of class, function, module that uses this library :param pip\_install: pip install command, if any :param msg: Descriptive message, if any + +Two more uncommon errors relate to failures in reading user-configuration files, or specifying a filename that cannot be used: + +### QiskitUserConfigError + + + +`qiskit.exceptions.QiskitUserConfigError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/exceptions.py "view source code") + +Raised when an error is encountered reading a user config file. + +Set the error message. + +### InvalidFileError + + + +`qiskit.exceptions.InvalidFileError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/exceptions.py "view source code") + +Raised when the file provided is not valid for the specific task. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/execute.md b/docs/api/qiskit/0.46/execute.md new file mode 100644 index 00000000000..963a49fe490 --- /dev/null +++ b/docs/api/qiskit/0.46/execute.md @@ -0,0 +1,183 @@ +--- +title: execute_function +description: API reference for qiskit.execute_function +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.execute_function +--- + + + + + + + +# Executing Experiments + + + +`qiskit.execute_function` + +### execute + + + +`qiskit.execute_function.execute(experiments, backend, basis_gates=None, coupling_map=None, backend_properties=None, initial_layout=None, seed_transpiler=None, optimization_level=None, pass_manager=None, shots=None, memory=None, seed_simulator=None, default_qubit_los=None, default_meas_los=None, qubit_lo_range=None, meas_lo_range=None, schedule_los=None, meas_level=None, meas_return=None, memory_slots=None, memory_slot_size=None, rep_time=None, rep_delay=None, parameter_binds=None, schedule_circuit=False, inst_map=None, meas_map=None, scheduling_method=None, init_qubits=None, **run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/execute_function.py "view source code") + +Execute a list of [`qiskit.circuit.QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") or [`qiskit.pulse.Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") on a backend. + +The execution is asynchronous, and a handle to a job instance is returned. + + + The function `qiskit.execute_function.execute()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function combines `transpile` and `backend.run`, which is covered by `Sampler` [`primitives`](primitives#module-qiskit.primitives "qiskit.primitives"). Alternatively, you can also run [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") followed by `backend.run()`. + + +**Parameters** + +* **experiments** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] or* [*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule")*]*) – Circuit(s) or pulse schedule(s) to execute + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – Backend to execute circuits on. Transpiler options are automatically grabbed from backend.configuration() and backend.properties(). If any other option is explicitly set (e.g. coupling\_map), it will override the backend’s. + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – List of basis gate names to unroll to. e.g: `['u1', 'u2', 'u3', 'cx']`. If `None`, do not unroll. + +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – + + Coupling map (perhaps custom) to target in mapping. Multiple formats are supported: + + 1. [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") instance + 2. `list`: must be given as an adjacency matrix, where each entry specifies all two-qubit interactions supported by backend e.g: `[[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]` + +* **backend\_properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – Properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. Find a backend that provides this information with: `backend.properties()` + +* **initial\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout") *or*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – + + Initial position of virtual qubits on physical qubits. If this layout makes the circuit compatible with the coupling\_map constraints, it will be used. The final layout is not guaranteed to be the same, as the transpiler may permute qubits through swaps or other means. + + Multiple formats are supported: + + 1. [`qiskit.transpiler.Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") instance + + 2. `dict`: + + * virtual to physical: + + ```python + {qr[0]: 0, + qr[1]: 3, + qr[2]: 5} + ``` + + * physical to virtual: + + ```python + {0: qr[0], + 3: qr[1], + 5: qr[2]} + ``` + + 3. `list`: + + * virtual to physical: + + ```python + [0, 3, 5] # virtual qubits are ordered (in addition to named) + ``` + + * physical to virtual: + + ```python + [qr[0], None, None, qr[1], None, qr[2]] + ``` + +* **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets random seed for the stochastic parts of the transpiler + +* **optimization\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – + + How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time. + + * 0: no optimization + * 1: light optimization + * 2: heavy optimization + * 3: even heavier optimization + + If None, level 1 will be chosen as default. + +* **pass\_manager** ([*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager")) – The pass manager to use during transpilation. If this arg is present, auto-selection of pass manager based on the transpile options will be turned off and this pass manager will be used directly. + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of repetitions of each circuit, for sampling. Default: 1024 + +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. Default: False + +* **seed\_simulator** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Random seed to control sampling, for when backend is a simulator + +* **default\_qubit\_los** (*Optional\[List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – List of job level qubit drive LO frequencies in Hz. Overridden by `schedule_los` if specified. Must have length `n_qubits`. + +* **default\_meas\_los** (*Optional\[List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – List of job level measurement LO frequencies in Hz. Overridden by `schedule_los` if specified. Must have length `n_qubits`. + +* **qubit\_lo\_range** (*Optional\[List\[List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]]*) – List of job level drive LO ranges each of form `[range_min, range_max]` in Hz. Used to validate `qubit_lo_freq`. Must have length `n_qubits`. + +* **meas\_lo\_range** (*Optional\[List\[List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]]*) – List of job level measurement LO ranges each of form `[range_min, range_max]` in Hz. Used to validate `meas_lo_freq`. Must have length `n_qubits`. + +* **schedule\_los** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – + + Experiment level (ie circuit or schedule) LO frequency configurations for qubit drive and measurement channels. These values override the job level values from `default_qubit_los` and `default_meas_los`. Frequencies are in Hz. Settable for qasm and pulse jobs. + + If a single LO config or dict is used, the values are set at job level. If a list is used, the list must be the size of the number of experiments in the job, except in the case of a single experiment. In this case, a frequency sweep will be assumed and one experiment will be created for every list entry. + + Not every channel is required to be specified. If not specified, the backend default value will be used. + +* **meas\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or MeasLevel*) – Set the appropriate level of the measurement output for pulse experiments. + +* **meas\_return** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or MeasReturn*) – Level of measurement data for the backend to return For `meas_level` 0 and 1: `"single"` returns information from every shot. `"avg"` returns average measurement output (averaged over number of shots). + +* **memory\_slots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of classical memory slots used in this job. + +* **memory\_slot\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Size of each memory slot if the output is Level 0. + +* **rep\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time per program execution in seconds. Must be from the list provided by the backend (`backend.configuration().rep_times`). Defaults to the first entry. + +* **rep\_delay** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Delay between programs in seconds. Only supported on certain backends (`backend.configuration().dynamic_reprate_enabled` ). If supported, `rep_delay` will be used instead of `rep_time` and must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. + +* **parameter\_binds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*]*) – List of Parameter bindings over which the set of experiments will be executed. Each list element (bind) should be of the form `{Parameter1: value1, Parameter2: value2, ...}`. All binds will be executed across all experiments, e.g. if parameter\_binds is a length-$n$ list, and there are $m$ experiments, a total of $m \times n$ experiments will be run (one for each experiment/bind pair). + +* **schedule\_circuit** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, `experiments` will be converted to [`qiskit.pulse.Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects prior to execution. + +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")) – Mapping of circuit operations to pulse schedules. If None, defaults to the `instruction_schedule_map` of `backend`. + +* **meas\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*))*) – List of sets of qubits that must be measured together. If None, defaults to the `meas_map` of `backend`. + +* **scheduling\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*)*) – Optionally specify a particular scheduling method. + +* **init\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reset the qubits to the ground state for each shot. Default: `True`. + +* **run\_config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Extra arguments used to configure the run (e.g. for Aer configurable backends). Refer to the backend documentation for details on these arguments. Note: for now, these keyword arguments will both be copied to the Qobj config, and passed to backend.run() + +**Returns** + +returns job instance derived from Job + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the execution cannot be interpreted as either circuits or schedules + +**Example** + +Construct a 5-qubit GHZ circuit and execute 4321 shots on a backend. + +```python +from qiskit import QuantumCircuit, execute, BasicAer + +backend = BasicAer.get_backend('qasm_simulator') + +qc = QuantumCircuit(5, 5) +qc.h(0) +qc.cx(0, range(1, 5)) +qc.measure_all() + +job = execute(qc, backend, shots=4321) +``` + diff --git a/docs/api/qiskit/0.46/extensions.md b/docs/api/qiskit/0.46/extensions.md new file mode 100644 index 00000000000..edc82a15983 --- /dev/null +++ b/docs/api/qiskit/0.46/extensions.md @@ -0,0 +1,50 @@ +--- +title: extensions +description: API reference for qiskit.extensions +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.extensions +--- + + + + + + + +# Quantum Circuit Extensions + + + +`qiskit.extensions` + +## Unitary Extensions + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| [`SingleQubitUnitary`](qiskit.extensions.SingleQubitUnitary "qiskit.extensions.SingleQubitUnitary")(unitary\_matrix\[, mode, ...]) | Single-qubit unitary. | + +## Simulator Extensions + +| | | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| [`Snapshot`](qiskit.extensions.Snapshot "qiskit.extensions.Snapshot")(label\[, snapshot\_type, num\_qubits, ...]) | Simulator snapshot instruction. | + +## Exceptions + +The additional gates in this module will tend to raise a custom exception when they encounter problems. + +### ExtensionError + + + +`qiskit.extensions.ExtensionError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/extensions/exceptions.py "view source code") + +Base class for errors raised by extensions module. + +Set the error message. + + + The class `qiskit.extensions.exceptions.ExtensionError` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + diff --git a/docs/api/qiskit/0.46/index.md b/docs/api/qiskit/0.46/index.md new file mode 100644 index 00000000000..bf7f3e9df70 --- /dev/null +++ b/docs/api/qiskit/0.46/index.md @@ -0,0 +1,64 @@ +--- +title: qiskit +description: API reference for qiskit +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit +--- + + + +# API Reference + +* [Quantum Circuits (`qiskit.circuit`)](circuit) +* [Circuit Library (`qiskit.circuit.library`)](circuit_library) +* [Classical expressions (`qiskit.circuit.classical`)](circuit_classical) +* [Singleton instructions (`qiskit.circuit.singleton`)](circuit_singleton) +* [Compilation Routines (`qiskit.compiler`)](compiler) +* [Executing Experiments (`qiskit.execute_function`)](execute) +* [Visualizations (`qiskit.visualization`)](visualization) +* [ClassicalFunction compiler (`qiskit.circuit.classicalfunction`)](classicalfunction) +* [Circuit Converters (`qiskit.converters`)](converters) +* [Circuit and Schedule Assembler (`qiskit.assembler`)](assembler) +* [DAG Circuits (`qiskit.dagcircuit`)](dagcircuit) +* [Quantum Circuit Extensions (`qiskit.extensions`)](extensions) +* [Passmanager (`qiskit.passmanager`)](passmanager) +* [Providers Interface (`qiskit.providers`)](providers) +* [Writing a New Provider](providers#writing-a-new-provider) +* [Migrating between Backend API Versions](providers#migrating-between-backend-api-versions) +* [BasicAer: Python-based Simulators (`qiskit.providers.basicaer`)](providers_basicaer) +* [BasicProvider: Python-based Simulators (`qiskit.providers.basic_provider`)](providers_basic_provider) +* [Fake Provider (`qiskit.providers.fake_provider`)](providers_fake_provider) +* [Backend Objects (`qiskit.providers.models`)](providers_models) +* [Pulse (`qiskit.pulse`)](pulse) +* [Circuit Scheduler (`qiskit.scheduler`)](scheduler) +* [Circuit Synthesis (`qiskit.synthesis`)](synthesis) +* [Primitives (`qiskit.primitives`)](primitives) +* [OpenQASM 2 (`qiskit.qasm2`)](qasm2) +* [OpenQASM 3 (`qiskit.qasm3`)](qasm3) +* [Qasm (`qiskit.qasm`)](qasm) +* [Qobj (`qiskit.qobj`)](qobj) +* [QPY serialization (`qiskit.qpy`)](qpy) +* [Quantum Information (`qiskit.quantum_info`)](quantum_info) +* [Experiment Results (`qiskit.result`)](result) +* [Qiskit Tools (`qiskit.tools`)](tools) +* [Jupyter Tools (`qiskit.tools.jupyter`)](tools_jupyter) +* [Transpiler (`qiskit.transpiler`)](transpiler) +* [Transpiler Passes (`qiskit.transpiler.passes`)](transpiler_passes) +* [Preset Passmanagers (`qiskit.transpiler.preset_passmanagers`)](transpiler_preset) +* [Transpiler Stage Plugin Interface (`qiskit.transpiler.preset_passmanagers.plugin`)](transpiler_plugins) +* [Synthesis Plugins (`qiskit.transpiler.passes.synthesis.plugin`)](transpiler_synthesis_plugins) +* [Built-in Transpiler Synthesis Plugins](transpiler_builtin_plugins) +* [Utilities (`qiskit.utils`)](utils) +* [Measurement Mitigation Utils (`qiskit.utils.mitigation`)](utils_mitigation) +* [Top-level exceptions (`qiskit.exceptions`)](exceptions) + +## Deprecated Modules + + + These modules are going to be removed in Qiskit 1.0. Consider pinning `qiskit~=0.45` in your dependencies if you need them. + + +* [Algorithms (`qiskit.algorithms`)](algorithms) +* [Operators (`qiskit.opflow`)](opflow) + diff --git a/docs/api/qiskit/0.46/opflow.md b/docs/api/qiskit/0.46/opflow.md new file mode 100644 index 00000000000..b4f9e0a0651 --- /dev/null +++ b/docs/api/qiskit/0.46/opflow.md @@ -0,0 +1,214 @@ +--- +title: opflow +description: API reference for qiskit.opflow +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow +--- + + + + + + + +# Operators + + + +`qiskit.opflow` + + + The [`qiskit.opflow`](#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +Operators and State functions are the building blocks of Quantum Algorithms. + +A library for Quantum Algorithms & Applications is more than a collection of algorithms wrapped in Python functions. It needs to provide tools to make writing algorithms simple and easy. This is the layer of modules between the circuits and algorithms, providing the language and computational primitives for QA\&A research. + +We call this layer the Operator Flow. It works by unifying computation with theory through the common language of functions and operators, in a way which preserves physical intuition and programming freedom. In the Operator Flow, we construct functions over binary variables, manipulate those functions with operators, and evaluate properties of these functions with measurements. + +The Operator Flow is meant to serve as a lingua franca between the theory and implementation of Quantum Algorithms & Applications. Meaning, the ultimate goal is that when theorists speak their theory in the Operator Flow, they are speaking valid implementation, and when the engineers speak their implementation in the Operator Flow, they are speaking valid physical formalism. To be successful, it must be fast and physically formal enough for theorists to find it easier and more natural than hacking Matlab or NumPy, and the engineers must find it straightforward enough that they can learn it as a typical software library, and learn the physics naturally and effortlessly as they learn the code. There can never be a point where we say “below this level this is all hacked out, don’t come down here, stay in the interface layer above.” It all must be clear and learnable. + +Before getting into the details of the code, it’s important to note that three mathematical concepts unpin the Operator Flow. We derive most of the inspiration for the code structure from [John Watrous’s formalism](https://cs.uwaterloo.ca/~watrous/TQI/) (but do not follow it exactly), so it may be worthwhile to review Chapters I and II, which are free online, if you feel the concepts are not clicking. + +1\. An n-qubit State function is a complex function over n binary variables, which we will often refer to as *n-qubit binary strings*. For example, the traditional quantum “zero state” is a 1-qubit state function, with a definition of f(0) = 1 and f(1) = 0. + +2\. An n-qubit Operator is a linear function taking n-qubit state functions to n-qubit state functions. For example, the Pauli X Operator is defined by f(Zero) = One and f(One) = Zero. Equivalently, an Operator can be defined as a complex function over two n-qubit binary strings, and it is sometimes convenient to picture things this way. By this definition, our Pauli X can be defined by its typical matrix elements, f(0, 0) = 0, f(1, 0) = 1, f(0, 1) = 1, f(1, 1) = 0. + +3\. An n-qubit Measurement is a functional taking n-qubit State functions to complex values. For example, a Pauli Z Measurement can be defined by f(Zero) = 0 and f(One) = 1. + + + While every effort has been made to make programming the Operator Flow similar to mathematical notation, in some places our hands are tied by the design of Python. In particular, when using mathematical operators such as `+` and `^` (tensor product), beware that these follow [Python operator precedence rules](https://docs.python.org/3/reference/expressions.html#operator-precedence). For example, `I^X + X^I` will actually be interpreted as `I ^ (X+X) ^ I == 2 * I^X^I`. In these cases, you should use extra parentheses, like `(I ^ X) + (X ^ I)`, or use the relevant method calls. + + +Below, you’ll find a base class for all Operators, some convenience immutable global variables which simplify Operator construction, and two groups of submodules: Operators and Converters. + +## Operator Base Class + +The OperatorBase serves as the base class for all Operators, State functions and measurements, and enforces the presence and consistency of methods to manipulate these objects conveniently. + +| | | +| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| [`OperatorBase`](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")() | Deprecated: A base class for all Operators: PrimitiveOps, StateFns, ListOps, etc. | + + + +## Operator Globals + +The `operator_globals` is a set of immutable Operator instances that are convenient building blocks to reach for while working with the Operator flow. + +**One qubit Pauli operators:** + +`X`, `Y`, `Z`, `I` + +**Clifford+T, and some other common non-parameterized gates:** + +`CX`, `S`, `H`, `T`, `Swap`, `CZ` + +**One qubit states:** + +`Zero`, `One`, `Plus`, `Minus` + +## Submodules + +### Operators + +The Operators submodules include the PrimitiveOp, ListOp, and StateFn class groups which represent the primary Operator modules. + +| | | +| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| [`primitive_ops`](qiskit.opflow.primitive_ops#module-qiskit.opflow.primitive_ops "qiskit.opflow.primitive_ops") | Primitive Operators (qiskit.opflow\.primitive\_ops) | +| [`list_ops`](qiskit.opflow.list_ops#module-qiskit.opflow.list_ops "qiskit.opflow.list_ops") | List Operators (qiskit.opflow\.list\_ops) | +| [`state_fns`](qiskit.opflow.state_fns#module-qiskit.opflow.state_fns "qiskit.opflow.state_fns") | State Functions (qiskit.opflow\.state\_fns) | + +### Converters + +The Converter submodules include objects which manipulate Operators, usually recursing over an Operator structure and changing certain Operators’ representation. For example, the [`PauliExpectation`](qiskit.opflow.expectations.PauliExpectation "qiskit.opflow.expectations.PauliExpectation") traverses an Operator structure, and replaces all of the [`OperatorStateFn`](qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.OperatorStateFn") measurements containing non-diagonal Pauli terms into diagonalizing circuits following by [`OperatorStateFn`](qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.OperatorStateFn") measurement containing only diagonal Paulis. + +| | | +| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| [`converters`](qiskit.opflow.converters#module-qiskit.opflow.converters "qiskit.opflow.converters") | Converters (qiskit.opflow\.converters) | +| [`evolutions`](qiskit.opflow.evolutions#module-qiskit.opflow.evolutions "qiskit.opflow.evolutions") | Operator Evolutions (qiskit.opflow\.evolutions) | +| [`expectations`](qiskit.opflow.expectations#module-qiskit.opflow.expectations "qiskit.opflow.expectations") | Expectations (qiskit.opflow\.expectations) | +| [`gradients`](qiskit.opflow.gradients#module-qiskit.opflow.gradients "qiskit.opflow.gradients") | Gradients (qiskit.opflow\.gradients) | + +## Utility functions + +### commutator + + + +`qiskit.opflow.commutator(op_a, op_b)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/utils.py "view source code") + +Deprecated: Compute commutator of op\_a and op\_b. + +$$ +AB - BA. +$$ + + + The function `qiskit.opflow.utils.commutator()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **op\_a** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator A +* **op\_b** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator B + +**Returns** + +the commutator + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") + +### anti\_commutator + + + +`qiskit.opflow.anti_commutator(op_a, op_b)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/utils.py "view source code") + +Deprecated: Compute anti-commutator of op\_a and op\_b. + +$$ +AB + BA. +$$ + + + The function `qiskit.opflow.utils.anti_commutator()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **op\_a** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator A +* **op\_b** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator B + +**Returns** + +the anti-commutator + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") + +### double\_commutator + + + +`qiskit.opflow.double_commutator(op_a, op_b, op_c, sign=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/utils.py "view source code") + +Deprecated: Compute symmetric double commutator of op\_a, op\_b and op\_c. See McWeeny chapter 13.6 Equation of motion methods (page 479) + +If sign is False, it returns + +$$ +[[A, B], C]/2 + [A, [B, C]]/2 += (2ABC + 2CBA - BAC - CAB - ACB - BCA)/2. +$$ + +If sign is True, it returns + +$$ +\lbrace[A, B], C\rbrace/2 + \lbrace A, [B, C]\rbrace/2 += (2ABC - 2CBA - BAC + CAB - ACB + BCA)/2. + + +$$ + + + The function `qiskit.opflow.utils.double_commutator()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **op\_a** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator A +* **op\_b** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator B +* **op\_c** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator C +* **sign** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – False anti-commutes, True commutes + +**Returns** + +the double commutator + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") + +## Exceptions + +### OpflowError + + + +`qiskit.opflow.OpflowError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/exceptions.py "view source code") + +Deprecated: For Opflow specific errors. + +Set the error message. + + + The class `qiskit.opflow.exceptions.OpflowError` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + diff --git a/docs/api/qiskit/0.46/passmanager.md b/docs/api/qiskit/0.46/passmanager.md new file mode 100644 index 00000000000..d50b5df0a65 --- /dev/null +++ b/docs/api/qiskit/0.46/passmanager.md @@ -0,0 +1,173 @@ +--- +title: passmanager +description: API reference for qiskit.passmanager +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.passmanager +--- + + + + + + + +# Passmanager + + + +`qiskit.passmanager` + +## Overview + +The Qiskit pass manager is somewhat inspired by the [LLVM compiler](https://llvm.org/), but it is designed to take a Python object as an input instead of plain source code. + +The pass manager converts the input Python object into an intermediate representation (IR), and it can be optimized and get lowered with a variety of transformations over multiple passes. The pass manager framework may employ multiple IRs with interleaved conversion passes, depending on the context of the optimization. + + + Currently there is no actual use/design of multiple IRs in the builtin Qiskit pass managers. The implementation of the `passmanager` module is agnostic to actual IR types (i.e. no strict type check is performed), and the pass manager works as long as the IR implements all methods required by subsequent passes. A concrete design for the use of multiple IRs might be provided in the future release. + + +The passes may consume the hardware constraints that the Qiskit backend may provide. Finally, the IR is converted back to some Python object. Note that the input type and output type are not necessarily the same. + +Compilation in the pass manager is a chain of `Task` executions that take an IR and output a new IR with some optimization or data analysis. An atomic task is a *pass* which is a subclass of [`GenericPass`](qiskit.passmanager.GenericPass "qiskit.passmanager.GenericPass") that implements a `run()` method that performs some work on the received IR. A set of passes may form a *flow controller*, which is a subclass of [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.BaseController"), which can implement arbitrary compilation-state-dependent logic for deciding which pass will get run next. Passes share intermediate data via the [`PropertySet`](qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") object which is a free-form dictionary. A pass can populate the property set dictionary during the task execution. A flow controller can also consume the property set to control the pass execution, but this access must be read-only. The property set is portable and handed over from pass to pass at execution. In addition to the property set, tasks also receive a [`WorkflowStatus`](qiskit.passmanager.WorkflowStatus "qiskit.passmanager.WorkflowStatus") data structure. This object is initialized when the pass manager is run and handed over to underlying tasks. The status is updated after every pass is run, and contains information about the pipeline state (number of passes run, failure state, and so on) as opposed to the [`PropertySet`](qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet"), which contains information about the IR being optimized. + +A pass manager is a wrapper of the flow controller, with responsibilities of + +* Scheduling optimization tasks, +* Converting an input Python object to a particular Qiskit IR, +* Initializing a property set and workflow status, +* Running scheduled tasks to apply a series of transformations to the IR, +* Converting the IR back to an output Python object. + +This indicates that the flow controller itself is type-agnostic, and a developer must implement a subclass of the [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager") to manage the data conversion steps. This *veil of ignorance* allows us to choose the most efficient data representation for a particular pass manager task, while we can reuse the flow control machinery for different input and output types. + +A single flow controller always takes a single IR object, and returns a single IR object. Parallelism for multiple input objects is supported by the [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager") by broadcasting the flow controller via the `qiskit.tools.parallel_map()` function. + +## Examples + +We look into a toy optimization task, namely, preparing a row of numbers and remove a digit if the number is five. Such task might be easily done by converting the input numbers into string. We use the pass manager framework here, putting the efficiency aside for a moment to learn how to build a custom Qiskit compiler. + +```python +from qiskit.passmanager import BasePassManager, GenericPass, ConditionalController + +class ToyPassManager(BasePassManager): + + def _passmanager_frontend(self, input_program: int, **kwargs) -> str: + return str(input_program) + + def _passmanager_backend(self, passmanager_ir: str, in_program: int, **kwargs) -> int: + return int(passmanager_ir) +``` + +This pass manager inputs and outputs an integer number, while performing the optimization tasks on a string data. Hence, input, IR, output type are integer, string, integer, respectively. The `_passmanager_frontend()` method defines the conversion from the input data to IR, and `_passmanager_backend()` defines the conversion from the IR to output data. The pass manager backend is also given an `in_program` parameter that contains the original `input_program` to the front end, for referencing any original metadata of the input program for the final conversion. + +Next, we implement a pass that removes a digit when the number is five. + +```python +class RemoveFive(GenericPass): + + def run(self, passmanager_ir: str): + return passmanager_ir.replace("5", "") + +task = RemoveFive() +``` + +Finally, we instantiate a pass manager and schedule the task with it. Running the pass manager with random row of numbers returns new numbers that don’t contain five. + +```python +pm = ToyPassManager() +pm.append(task) + +pm.run([123456789, 45654, 36785554]) +``` + +Output: + +```python +[12346789, 464, 36784] +``` + +Now we consider the case of conditional execution. We avoid execution of the “remove five” task when the input number is six digits or less. Such control can be implemented by a flow controller. We start from an analysis pass that provides the flow controller with information about the number of digits. + +```python +class CountDigits(GenericPass): + + def run(self, passmanager_ir: str): + self.property_set["ndigits"] = len(passmanager_ir) + +analysis_task = CountDigits() +``` + +Then, we wrap the remove five task with the [`ConditionalController`](qiskit.passmanager.ConditionalController "qiskit.passmanager.ConditionalController") that runs the stored tasks only when the condition is met. + +```python +def digit_condition(property_set): + # Return True when condition is met. + return property_set["ndigits"] > 6 + +conditional_task = ConditionalController( + tasks=[RemoveFive()], + condition=digit_condition, +) +``` + +As before, we schedule these passes with the pass manager and run. + +```python +pm = ToyPassManager() +pm.append(analysis_task) +pm.append(conditional_task) + +pm.run([123456789, 45654, 36785554]) +``` + +Output: + +```python +[12346789, 45654, 36784] +``` + +The “remove five” task is triggered only for the first and third input values, which have more than six digits. + +With the pass manager framework, a developer can flexibly customize the optimization task by combining multiple passes and flow controllers. See details for following class API documentations. + +## Interface + +### Base classes + +| | | +| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager")(\[tasks, max\_iteration]) | Pass manager base class. | +| [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.BaseController")(\[options]) | Base class of controller. | +| [`GenericPass`](qiskit.passmanager.GenericPass "qiskit.passmanager.GenericPass")() | Base class of a single pass manager task. | + +### Flow controllers + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [`FlowController`](qiskit.passmanager.FlowController "qiskit.passmanager.FlowController")(\[options]) | A legacy factory for other flow controllers. | +| [`FlowControllerLinear`](qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.FlowControllerLinear")(\[tasks, options]) | A standard flow controller that runs tasks one after the other. | +| [`ConditionalController`](qiskit.passmanager.ConditionalController "qiskit.passmanager.ConditionalController")(\[tasks, condition, ...]) | A flow controller runs the pipeline once if the condition is true, or does nothing if the condition is false. | +| [`DoWhileController`](qiskit.passmanager.DoWhileController "qiskit.passmanager.DoWhileController")(\[tasks, do\_while, options]) | Run the given tasks in a loop until the `do_while` condition on the property set becomes `False`. | + +### Compilation state + +| | | +| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| [`PropertySet`](qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") | A default dictionary-like object. | +| [`WorkflowStatus`](qiskit.passmanager.WorkflowStatus "qiskit.passmanager.WorkflowStatus")(\[count, completed\_passes, ...]) | Collection of compilation status of workflow, i.e. pass manager run. | +| [`PassManagerState`](qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")(workflow\_status, property\_set) | A portable container object that pass manager tasks communicate through generator. | + +### Exceptions + +### PassManagerError + + + +`qiskit.passmanager.PassManagerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/exceptions.py "view source code") + +Pass manager error. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/primitives.md b/docs/api/qiskit/0.46/primitives.md new file mode 100644 index 00000000000..dc91d1f7812 --- /dev/null +++ b/docs/api/qiskit/0.46/primitives.md @@ -0,0 +1,146 @@ +--- +title: primitives +description: API reference for qiskit.primitives +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.primitives +--- + + + + + + + + + +# Primitives + + + +`qiskit.primitives` + +## Overview of Estimator + +Estimator class estimates expectation values of quantum circuits and observables. + +An estimator is initialized with an empty parameter set. The estimator is used to create a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1"), via the [`qiskit.primitives.Estimator.run()`](qiskit.primitives.Estimator#run "qiskit.primitives.Estimator.run") method. This method is called with the following parameters + +* quantum circuits ($\psi_i(\theta)$): list of (parameterized) quantum circuits (a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects). +* observables ($H_j$): a list of [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") objects. +* parameter values ($\theta_k$): list of sets of values to be bound to the parameters of the quantum circuits (list of list of float). + +The method returns a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") object, calling [`qiskit.providers.JobV1.result()`](qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") yields the a list of expectation values plus optional metadata like confidence intervals for the estimation. + +$$ +\langle\psi_i(\theta_k)|H_j|\psi_i(\theta_k)\rangle +$$ + +Here is an example of how the estimator is used. + +```python +from qiskit.primitives import Estimator +from qiskit.circuit.library import RealAmplitudes +from qiskit.quantum_info import SparsePauliOp + +psi1 = RealAmplitudes(num_qubits=2, reps=2) +psi2 = RealAmplitudes(num_qubits=2, reps=3) + +H1 = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)]) +H2 = SparsePauliOp.from_list([("IZ", 1)]) +H3 = SparsePauliOp.from_list([("ZI", 1), ("ZZ", 1)]) + +theta1 = [0, 1, 1, 2, 3, 5] +theta2 = [0, 1, 1, 2, 3, 5, 8, 13] +theta3 = [1, 2, 3, 4, 5, 6] + +estimator = Estimator() + +# calculate [ ] +job = estimator.run([psi1], [H1], [theta1]) +job_result = job.result() # It will block until the job finishes. +print(f"The primitive-job finished with result {job_result}")) + +# calculate [ , +# , +# ] +job2 = estimator.run([psi1, psi2, psi1], [H1, H2, H3], [theta1, theta2, theta3]) +job_result = job2.result() +print(f"The primitive-job finished with result {job_result}") +``` + + + +## Overview of Sampler + +Sampler class calculates probabilities or quasi-probabilities of bitstrings from quantum circuits. + +A sampler is initialized with an empty parameter set. The sampler is used to create a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1"), via the [`qiskit.primitives.Sampler.run()`](qiskit.primitives.Sampler#run "qiskit.primitives.Sampler.run") method. This method is called with the following parameters + +* quantum circuits ($\psi_i(\theta)$): list of (parameterized) quantum circuits. (a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects) +* parameter values ($\theta_k$): list of sets of parameter values to be bound to the parameters of the quantum circuits. (list of list of float) + +The method returns a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") object, calling [`qiskit.providers.JobV1.result()`](qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") yields a [`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.SamplerResult") object, which contains probabilities or quasi-probabilities of bitstrings, plus optional metadata like error bars in the samples. + +Here is an example of how sampler is used. + +```python +from qiskit.primitives import Sampler +from qiskit import QuantumCircuit +from qiskit.circuit.library import RealAmplitudes + +# a Bell circuit +bell = QuantumCircuit(2) +bell.h(0) +bell.cx(0, 1) +bell.measure_all() + +# two parameterized circuits +pqc = RealAmplitudes(num_qubits=2, reps=2) +pqc.measure_all() +pqc2 = RealAmplitudes(num_qubits=2, reps=3) +pqc2.measure_all() + +theta1 = [0, 1, 1, 2, 3, 5] +theta2 = [0, 1, 2, 3, 4, 5, 6, 7] + +# initialization of the sampler +sampler = Sampler() + +# Sampler runs a job on the Bell circuit +job = sampler.run(circuits=[bell], parameter_values=[[]], parameters=[[]]) +job_result = job.result() +print([q.binary_probabilities() for q in job_result.quasi_dists]) + +# Sampler runs a job on the parameterized circuits +job2 = sampler.run( + circuits=[pqc, pqc2], + parameter_values=[theta1, theta2], + parameters=[pqc.parameters, pqc2.parameters]) +job_result = job2.result() +print([q.binary_probabilities() for q in job_result.quasi_dists]) +``` + +## Estimator + +| | | +| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")(\*\[, options]) | Estimator base class. | +| [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator")(\*\[, options]) | Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"). | +| [`BackendEstimator`](qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator")(backend\[, options, ...]) | Evaluates expectation value using Pauli rotation gates. | + +## Sampler + +| | | +| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")(\*\[, options]) | Sampler base class | +| [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler")(\*\[, options]) | Sampler class. | +| [`BackendSampler`](qiskit.primitives.BackendSampler "qiskit.primitives.BackendSampler")(backend\[, options, ...]) | A [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") implementation that provides an interface for leveraging the sampler interface from any backend. | + +## Results + +| | | +| ------------------------------------------------------------------------------------------------------------ | -------------------- | +| [`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.EstimatorResult")(values, metadata) | Result of Estimator. | +| [`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.SamplerResult")(quasi\_dists, metadata) | Result of Sampler. | + diff --git a/docs/api/qiskit/0.46/providers.md b/docs/api/qiskit/0.46/providers.md new file mode 100644 index 00000000000..eeee0fc05fb --- /dev/null +++ b/docs/api/qiskit/0.46/providers.md @@ -0,0 +1,509 @@ +--- +title: providers +description: API reference for qiskit.providers +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.providers +--- + + + + + + + +# Providers Interface + + + +`qiskit.providers` + +This module contains the classes used to build external providers for Terra. A provider is anything that provides an external service to Terra. The typical example of this is a Backend provider which provides [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") objects which can be used for executing [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") and/or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects. This module contains the abstract classes which are used to define the interface between a provider and terra. + +## Version Support + +Each providers interface abstract class is individually versioned. When we need to make a change to an interface a new abstract class will be created to define the new interface. These interface changes are not guaranteed to be backwards compatible between versions. + +### Version Changes + +Each minor version release of qiskit-terra **may** increment the version of any providers interface a single version number. It will be an aggregate of all the interface changes for that release on that interface. + +### Version Support Policy + +To enable providers to have time to adjust to changes in this interface Terra will support multiple versions of each class at once. Given the nature of one version per release the version deprecation policy is a bit more conservative than the standard deprecation policy. Terra will support a provider interface version for a minimum of 3 minor releases or the first release after 6 months from the release that introduced a version, whichever is longer, prior to a potential deprecation. After that the standard deprecation policy will apply to that interface version. This will give providers and users sufficient time to adapt to potential breaking changes in the interface. So for example lets say in 0.19.0 `BackendV2` is introduced and in the 3 months after the release of 0.19.0 we release 0.20.0, 0.21.0, and 0.22.0, then 7 months after 0.19.0 we release 0.23.0. In 0.23.0 we can deprecate BackendV2, and it needs to still be supported and can’t be removed until the deprecation policy completes. + +It’s worth pointing out that Terra’s version support policy doesn’t mean providers themselves will have the same support story, they can (and arguably should) update to newer versions as soon as they can, the support window is just for Terra’s supported versions. Part of this lengthy window prior to deprecation is to give providers enough time to do their own deprecation of a potential end user impacting change in a user facing part of the interface prior to bumping their version. For example, let’s say we changed the signature to `Backend.run()` in `BackendV34` in a backwards incompatible way. Before Aer could update its [`AerSimulator`](https://qiskit.org/ecosystem/aer/stubs/qiskit_aer.AerSimulator.html#qiskit_aer.AerSimulator "(in Qiskit Aer v0.13.1)") class to be based on version 34 they’d need to deprecate the old signature prior to switching over. The changeover for Aer is not guaranteed to be lockstep with Terra so we need to ensure there is a sufficient amount of time for Aer to complete its deprecation cycle prior to removing version 33 (ie making version 34 mandatory/the minimum version). + +## Abstract Classes + +### Provider + +| | | +| --------------------------------------------------------------------------- | ------------------------------------------------------------- | +| [`Provider`](qiskit.providers.Provider "qiskit.providers.Provider")() | Base common type for all versioned Provider abstract classes. | +| [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.ProviderV1")() | Base class for a Backend Provider. | + +### Backend + +| | | +| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend")() | Base common type for all versioned Backend abstract classes. | +| [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1")(configuration\[, provider]) | Abstract class for Backends | +| [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2")(\[provider, name, description, ...]) | Abstract class for Backends | +| [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties")(\[t1, t2, frequency]) | A representation of the properties of a qubit on a backend. | +| [`BackendV2Converter`](qiskit.providers.BackendV2Converter "qiskit.providers.BackendV2Converter")(backend\[, name\_mapping, ...]) | A converter class that takes a [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") instance and wraps it in a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") interface. | +| [`convert_to_target`](qiskit.providers.convert_to_target "qiskit.providers.convert_to_target")(configuration\[, ...]) | Uses configuration, properties and pulse defaults to construct and return Target class. | + +### Options + +| | | +| ---------------------------------------------------------------------------- | ------------------- | +| [`Options`](qiskit.providers.Options "qiskit.providers.Options")(\*\*kwargs) | Base options object | + +### Job + +| | | +| ---------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| [`Job`](qiskit.providers.Job "qiskit.providers.Job")() | Base common type for all versioned Job abstract classes. | +| [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1")(backend, job\_id, \*\*kwargs) | Class to handle jobs | + +### Job Status + +| | | +| ----------------------------------------------------------------------------- | ------------------------------------- | +| [`JobStatus`](qiskit.providers.JobStatus "qiskit.providers.JobStatus")(value) | Class for job status enumerated type. | + +### Exceptions + +### QiskitBackendNotFoundError + + + +`qiskit.providers.QiskitBackendNotFoundError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/exceptions.py "view source code") + +Base class for errors raised while looking for a backend. + +Set the error message. + +### BackendPropertyError + + + +`qiskit.providers.BackendPropertyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/exceptions.py "view source code") + +Base class for errors raised while looking for a backend property. + +Set the error message. + +### JobError + + + +`qiskit.providers.JobError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/exceptions.py "view source code") + +Base class for errors raised by Jobs. + +Set the error message. + +### JobTimeoutError + + + +`qiskit.providers.JobTimeoutError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/exceptions.py "view source code") + +Base class for timeout errors raised by jobs. + +Set the error message. + +### BackendConfigurationError + + + +`qiskit.providers.BackendConfigurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/exceptions.py "view source code") + +Base class for errors raised by the BackendConfiguration. + +Set the error message. + +# Writing a New Provider + +If you have a quantum device or simulator that you would like to integrate with Qiskit you will need to write a provider. A provider will provide Terra with a method to get available [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") objects. The [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") object provides both information describing a backend and its operation for the [`transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler") so that circuits can be compiled to something that is optimized and can execute on the backend. It also provides the [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method which can run the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects and/or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects. This enables users and other Qiskit APIs, such as [`execute()`](execute#qiskit.execute_function.execute "qiskit.execute_function.execute") and higher level algorithms in [`qiskit.algorithms`](algorithms#module-qiskit.algorithms "qiskit.algorithms"), to get results from executing circuits on devices in a standard fashion regardless of how the backend is implemented. At a high level the basic steps for writing a provider are: + +> * Implement a [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.ProviderV1") subclass that handles access to the backend(s). +> +> * Implement a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") subclass and its [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method. +> +> * Add any custom gates for the backend’s basis to the session [`EquivalenceLibrary`](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary") instance. +> +> * Implement a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") subclass that handles interacting with a running job. + +For a simple example of a provider, see the [qiskit-aqt-provider](https://github.com/Qiskit-Partners/qiskit-aqt-provider) + + + +## Provider + +A provider class serves a single purpose: to get backend objects that enable executing circuits on a device or simulator. The expectation is that any required credentials and/or authentication will be handled in the initialization of a provider object. The provider object will then provide a list of backends, and methods to filter and acquire backends (using the provided credentials if required). An example provider class looks like: + +```python +from qiskit.providers import ProviderV1 as Provider +from qiskit.providers.providerutils import filter_backends + +from .backend import MyBackend + +class MyProvider(Provider): + + def __init__(self, token=None): + super().__init__() + self.token = token + self.backends = [MyBackend(provider=self)] + + def backends(self, name=None, **kwargs): + if name: + backends = [ + backend for backend in backends if backend.name() == name] + return filter_backends(backends, filters=filters, **kwargs) +``` + +Ensure that any necessary information for authentication (if required) are present in the class and that the backends method matches the required interface. The rest is up to the specific provider on how to implement. + + + +## Backend + +The backend classes are the core to the provider. These classes are what provide the interface between Qiskit and the hardware or simulator that will execute circuits. This includes providing the necessary information to describe a backend to the compiler so that it can embed and optimize any circuit for the backend. There are 4 required things in every backend object: a [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") property to define the model of the backend for the compiler, a [`max_circuits`](qiskit.providers.BackendV2#max_circuits "qiskit.providers.BackendV2.max_circuits") property to define a limit on the number of circuits the backend can execute in a single batch job (if there is no limit `None` can be used), a [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method to accept job submissions, and a [`_default_options`](qiskit.providers.BackendV2#_default_options "qiskit.providers.BackendV2._default_options") method to define the user configurable options and their default values. For example, a minimum working example would be something like: + +```python +from qiskit.providers import BackendV2 as Backend +from qiskit.transpiler import Target +from qiskit.providers import Options +from qiskit.circuit import Parameter, Measure +from qiskit.circuit.library import PhaseGate, SXGate, UGate, CXGate, IGate + + +class Mybackend(Backend): + + def __init__(self): + super().__init__() + + # Create Target + self._target = Target("Target for My Backend") + # Instead of None for this and below instructions you can define + # a qiskit.transpiler.InstructionProperties object to define properties + # for an instruction. + lam = Parameter("λ") + p_props = {(qubit,): None for qubit in range(5)} + self._target.add_instruction(PhaseGate(lam), p_props) + sx_props = {(qubit,): None for qubit in range(5)} + self._target.add_instruction(SXGate(), sx_props) + phi = Parameter("φ") + theta = Parameter("ϴ") + u_props = {(qubit,): None for qubit in range(5)} + self._target.add_instruction(UGate(theta, phi, lam), u_props) + cx_props = {edge: None for edge in [(0, 1), (1, 2), (2, 3), (3, 4)]} + self._target.add_instruction(CXGate(), cx_props) + meas_props = {(qubit,): None for qubit in range(5)} + self._target.add_instruction(Measure(), meas_props) + id_props = {(qubit,): None for qubit in range(5)} + self._target.add_instruction(IGate(), id_props) + + # Set option validators + self.options.set_validator("shots", (1, 4096)) + self.options.set_validator("memory", bool) + + @property + def target(self): + return self._target + + @property + def max_circuits(self): + return 1024 + + @classmethod + def _default_options(cls): + return Options(shots=1024, memory=False) + + def run(circuits, **kwargs): + # serialize circuits submit to backend and create a job + for kwarg in kwargs: + if not hasattr(kwarg, self.options): + warnings.warn( + "Option %s is not used by this backend" % kwarg, + UserWarning, stacklevel=2) + options = { + 'shots': kwargs.get('shots', self.options.shots), + 'memory': kwargs.get('memory', self.options.shots), + } + job_json = convert_to_wire_format(circuit, options) + job_handle = submit_to_backend(job_jsonb) + return MyJob(self. job_handle, job_json, circuit) +``` + +### Transpiler Interface + +The key piece of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") object is how it describes itself to the compiler. This is handled with the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class which defines a model of a backend for the transpiler. A backend object will need to return a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object from the [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") attribute which the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function will use as its model of a backend target for compilation. + + + +#### Custom Basis Gates + +1. If your backend doesn’t use gates in the Qiskit circuit library ([`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library")) you can integrate support for this into your provider. The basic method for doing this is first to define a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") subclass for each custom gate in the basis set. For example: + + ```python + import numpy as np + + from qiskit.circuit import Gate + from qiskit.circuit import QuantumCircuit + + class SYGate(Gate): + def __init__(self, label=None): + super().__init__("sy", 1, [], label=label) + + def _define(self): + qc = QuantumCircuit(1) + q.ry(np.pi / 2, 0) + self.definition = qc + ``` + + The key thing to ensure is that for any custom gates in your Backend’s basis set your custom gate’s name attribute (the first param on `super().__init__()` in the `__init__` definition above) does not conflict with the name of any other gates. The name attribute is what is used to identify the gate in the basis set for the transpiler. If there is a conflict the transpiler will not know which gate to use. + +2. Add the custom gate to the target for your backend. This can be done with the [`Target.add_instruction()`](qiskit.transpiler.Target#add_instruction "qiskit.transpiler.Target.add_instruction") method. You’ll need to add an instance of `SYGate` and its parameters to the target so the transpiler knows it exists. For example, assuming this is part of your [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") implementation for your backend: + + ```python + from qiskit.transpiler import InstructionProperties + + sy_props = { + (0,): InstructionProperties(duration=2.3e-6, error=0.0002) + (1,): InstructionProperties(duration=2.1e-6, error=0.0001) + (2,): InstructionProperties(duration=2.5e-6, error=0.0003) + (3,): InstructionProperties(duration=2.2e-6, error=0.0004) + } + self.target.add_instruction(SYGate(), sy_props) + ``` + + The keys in `sy_props` define the qubits where the backend `SYGate` can be used on, and the values define the properties of `SYGate` on that qubit. For multiqubit gates the tuple keys contain all qubit combinations the gate works on (order is significant, i.e. `(0, 1)` is different from `(1, 0)`). + +3. After you’ve defined the custom gates to use for the backend’s basis set then you need to add equivalence rules to the standard equivalence library so that the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function and [`transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler") module can convert an arbitrary circuit using the custom basis set. This can be done by defining equivalent circuits, in terms of the custom gate, for standard gates. Typically if you can convert from a [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") (if your basis doesn’t include a standard 2 qubit gate) and some commonly used single qubit rotation gates like the [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate") and [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate") that should be sufficient for the transpiler to translate any circuit into the custom basis gates. But, the more equivalence rules that are defined from standard gates to your basis the more efficient translation from an arbitrary circuit to the target basis will be (although not always, and there is a diminishing margin of return). + + For example, if you were to add some rules for the above custom `SYGate` we could define the [`U2Gate`](qiskit.circuit.library.U2Gate "qiskit.circuit.library.U2Gate") and [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate"): + + ```python + from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary + from qiskit.circuit.library import HGate + from qiskit.circuit.library import ZGate + from qiskit.circuit.library import RZGate + from qiskit.circuit.library import U2Gate + + + # H => Z SY + q = qiskit.QuantumRegister(1, "q") + def_sy_h = qiskit.QuantumCircuit(q) + def_sy_h.append(ZGate(), [q[0]], []) + def_sy_h.append(SYGate(), [q[0]], []) + SessionEquivalenceLibrary.add_equivalence( + HGate(), def_sy_h) + + # u2 => Z SY Z + phi = qiskit.circuit.Parameter('phi') + lam = qiskit.circuit.Parameter('lambda') + q = qiskit.QuantumRegister(1, "q") + def_sy_u2 = qiskit.QuantumCircuit(q) + def_sy_u2.append(RZGate(lam), [q[0]], []) + def_sy_u2.append(SYGate(), [q[0]], []) + def_sy_u2.append(RZGate(phi), [q[0]], []) + SessionEquivalenceLibrary.add_equivalence( + U2Gate(phi, lam), def_sy_u2) + ``` + + You will want this to be run on import so that as soon as the provider’s package is imported it will be run. This will ensure that any time the [`BasisTranslator`](qiskit.transpiler.passes.BasisTranslator "qiskit.transpiler.passes.BasisTranslator") pass is run with the custom gates the equivalence rules are defined. + + It’s also worth noting that depending on the basis you’re using, some optimization passes in the transpiler, such as [`Optimize1qGatesDecomposition`](qiskit.transpiler.passes.Optimize1qGatesDecomposition "qiskit.transpiler.passes.Optimize1qGatesDecomposition"), may not be able to operate with your custom basis. For our `SYGate` example, the [`Optimize1qGatesDecomposition`](qiskit.transpiler.passes.Optimize1qGatesDecomposition "qiskit.transpiler.passes.Optimize1qGatesDecomposition") will not be able to simplify runs of single qubit gates into the SY basis. This is because the `OneQubitEulerDecomposer` class does not know how to work in the SY basis. To solve this the `SYGate` class would need to be added to Qiskit and `OneQubitEulerDecomposer` updated to support decomposing to the `SYGate`. Longer term that is likely a better direction for custom basis gates and contributing the definitions and support in the transpiler will ensure that it continues to be well supported by Qiskit moving forward. + + + +#### Custom Transpiler Passes + +The transpiler supports the ability for backends to provide custom transpiler stage implementations to facilitate hardware specific optimizations and circuit transformations. Currently there are two stages supported, `get_translation_stage_plugin()` and `get_scheduling_stage_plugin()` which allow a backend to specify string plugin names to be used as the default translation and scheduling stages, respectively. These hook points in a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") class can be used if your backend has requirements for compilation that are not met by the current backend/[`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") interface. Please also consider submitting a Github issue describing your use case as there is interest in improving these interfaces to be able to describe more hardware architectures in greater depth. + +To leverage these hook points you just need to add the methods to your [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") implementation and have them return a string plugin name. For example: + +```python +class Mybackend(BackendV2): + + def get_scheduling_stage_plugin(self): + return "SpecialDD" + + def get_translation_stage_plugin(self): + return "BasisTranslatorWithCustom1qOptimization" +``` + +This snippet of a backend implementation will now have the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function use the `SpecialDD` plugin for the scheduling stage and the `BasisTranslatorWithCustom1qOptimization` plugin for the translation stage by default when the target is set to `Mybackend`. Note that users may override these choices by explicitly selecting a different plugin name. For this interface to work though transpiler stage plugins must be implemented for the returned plugin name. You can refer to [`qiskit.transpiler.preset_passmanagers.plugin`](transpiler_plugins#module-qiskit.transpiler.preset_passmanagers.plugin "qiskit.transpiler.preset_passmanagers.plugin") module documentation for details on how to implement plugins. The typical expectation is that if your backend requires custom passes as part of a compilation stage the provider package will include the transpiler stage plugins that use those passes. However, this is not required and any valid method (from a built-in method or external plugin) can be used. + +This way if these two compilation steps are **required** for running or providing efficient output on `Mybackend` the transpiler will be able to perform these custom steps without any manual user input. + +### Run Method + +Of key importance is the [`run()`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method, which is used to actually submit circuits to a device or simulator. The run method handles submitting the circuits to the backend to be executed and returning a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. Depending on the type of backend this typically involves serializing the circuit object into the API format used by a backend. For example, on IBMQ backends from the `qiskit-ibmq-provider` package this involves converting from a quantum circuit and options into a [qobj](https://arxiv.org/abs/1809.03452) JSON payload and submitting that to the IBM Quantum API. Since every backend interface is different (and in the case of the local simulators serialization may not be needed) it is expected that the backend’s [`run`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method will handle this conversion. + +An example run method would be something like: + +```python +def run(self, circuits. **kwargs): + for kwarg in kwargs: + if not hasattr(kwarg, self.options): + warnings.warn( + "Option %s is not used by this backend" % kwarg, + UserWarning, stacklevel=2) + options = { + 'shots': kwargs.get('shots', self.options.shots) + 'memory': kwargs.get('memory', self.options.shots), + } + job_json = convert_to_wire_format(circuit, options) + job_handle = submit_to_backend(job_jsonb) + return MyJob(self. job_handle, job_json, circuit) +``` + + + +### Options + +There are often several options for a backend that control how a circuit is run. The typical example of this is something like the number of `shots` which is how many times the circuit is to be executed. The options available for a backend are defined using an [`Options`](qiskit.providers.Options "qiskit.providers.Options") object. This object is initially created by the [`_default_options`](qiskit.providers.BackendV2#_default_options "qiskit.providers.BackendV2._default_options") method of a Backend class. The default options returns an initialized [`Options`](qiskit.providers.Options "qiskit.providers.Options") object with all the default values for all the options a backend supports. For example, if the backend supports only supports `shots` the [`_default_options`](qiskit.providers.BackendV2#_default_options "qiskit.providers.BackendV2._default_options") method would look like: + +```python +@classmethod +def _default_options(cls): + return Options(shots=1024) +``` + +You can also set validators on an [`Options`](qiskit.providers.Options "qiskit.providers.Options") object to provide limits and validation on user provided values based on what’s acceptable for your backend. For example, if the `"shots"` option defined above can be set to any value between 1 and 4096 you can set the validator on the options object for you backend with: + +```python +self.options.set_validator("shots", (1, 4096)) +``` + +you can refer to the [`set_validator()`](qiskit.providers.Options#set_validator "qiskit.providers.Options.set_validator") documentation for a full list of validation options. + + + +## Job + +The output from the [`run`](qiskit.providers.BackendV2#run "qiskit.providers.BackendV2.run") method is a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") object. Each provider is expected to implement a custom job subclass that defines the behavior for the provider. There are 2 types of jobs depending on the backend’s execution method, either a sync or async. By default jobs are considered async and the expectation is that it represents a handle to the async execution of the circuits submitted with `Backend.run()`. An async job object provides users the ability to query the status of the execution, cancel a running job, and block until the execution is finished. The [`result`](qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") is the primary user facing method which will block until the execution is complete and then will return a [`Result`](qiskit.result.Result "qiskit.result.Result") object with results of the job. + +For some backends (mainly local simulators) the execution of circuits is a synchronous operation and there is no need to return a handle to a running job elsewhere. For sync jobs its expected that the [`run`](qiskit.providers.BackendV1#run "qiskit.providers.BackendV1.run") method on the backend will block until a [`Result`](qiskit.result.Result "qiskit.result.Result") object is generated and the sync job will return with that inner [`Result`](qiskit.result.Result "qiskit.result.Result") object. + +An example job class for an async API based backend would look something like: + +```python +from qiskit.providers import JobV1 as Job +from qiskit.providers import JobError +from qiskit.providers import JobTimeoutError +from qiskit.providers.jobstatus import JobStatus +from qiskit.result import Result + + +class MyJob(Job): + def __init__(self, backend, job_id, job_json, circuits): + super().__init__(backend, job_id) + self._backend = backend + self.job_json = job_json + self.circuits = circuits + + def _wait_for_result(self, timeout=None, wait=5): + start_time = time.time() + result = None + while True: + elapsed = time.time() - start_time + if timeout and elapsed >= timeout: + raise JobTimeoutError('Timed out waiting for result') + result = get_job_status(self._job_id) + if result['status'] == 'complete': + break + if result['status'] == 'error': + raise JobError('Job error') + time.sleep(wait) + return result + + def result(self, timeout=None, wait=5): + result = self._wait_for_result(timeout, wait) + results = [{'success': True, 'shots': len(result['counts']), + 'data': result['counts']}] + return Result.from_dict({ + 'results': results, + 'backend_name': self._backend.configuration().backend_name, + 'backend_version': self._backend.configuration().backend_version, + 'job_id': self._job_id, + 'qobj_id': ', '.join(x.name for x in self.circuits), + 'success': True, + }) + + def status(self): + result = get_job_status(self._job_id) + if result['status'] == 'running': + status = JobStatus.RUNNING + elif result['status'] == 'complete': + status = JobStatus.DONE + else: + status = JobStatus.ERROR + return status + +def submit(self): + raise NotImplementedError +``` + +and for a sync job: + +```python +class MySyncJob(Job): + _async = False + + def __init__(self, backend, job_id, result): + super().__init__(backend, job_id) + self._result = result + + def submit(self): + return + + def result(self): + return self._result + + def status(self): + return JobStatus.DONE +``` + +## Primitives + +While not directly part of the provider interface, the [`qiskit.primitives`](primitives#module-qiskit.primitives "qiskit.primitives") module is tightly coupled with providers. Specifically the primitive interfaces, such as [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") and [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"), are designed to enable provider implementations to provide custom implementations which are optimized for the provider’s backends. This can include customizations like circuit transformations, additional pre- and post-processing, batching, caching, error mitigation, etc. The concept of the [`qiskit.primitives`](primitives#module-qiskit.primitives "qiskit.primitives") module is to explicitly enable this as the primitive objects are higher level abstractions to produce processed higher level outputs (such as probability distributions and expectation values) that abstract away the mechanics of getting the best result efficiently, to concentrate on higher level applications using these outputs. + +For example, if your backends were well suited to leverage [mthree](https://github.com/Qiskit-Partners/mthree/) measurement mitigation to improve the quality of the results, you could implement a provider-specific [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler") implementation that leverages the `M3Mitigation` class internally to run the circuits and return quasi-probabilities directly from mthree in the result. Doing this would enable algorithms from [`qiskit.algorithms`](algorithms#module-qiskit.algorithms "qiskit.algorithms") to get the best results with mitigation applied directly from your backends. You can refer to the documentation in [`qiskit.primitives`](primitives#module-qiskit.primitives "qiskit.primitives") on how to write custom implementations. Also the built-in implementations: [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler"), [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator"), [`BackendSampler`](qiskit.primitives.BackendSampler "qiskit.primitives.BackendSampler"), and [`BackendEstimator`](qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator") can serve as references/models on how to implement these as well. + +# Migrating between Backend API Versions + + + +## BackendV1 -> BackendV2 + +The [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") class re-defined user access for most properties of a backend to make them work with native Qiskit data structures and have flatter access patterns. However this means when using a provider that upgrades from [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") to [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") existing access patterns will need to be adjusted. It is expected for existing providers to deprecate the old access where possible to provide a graceful migration, but eventually users will need to adjust code. The biggest change to adapt to in [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") is that most of the information accessible about a backend is contained in its [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object and the backend’s attributes often query its [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") attribute to return information, however in many cases the attributes only provide a subset of information the target can contain. For example, `backend.coupling_map` returns a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") constructed from the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") accessible in the [`target`](qiskit.providers.BackendV2#target "qiskit.providers.BackendV2.target") attribute, however the target may contain instructions that operate on more than two qubits (which can’t be represented in a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) or has instructions that only operate on a subset of qubits (or two qubit links for a two qubit instruction) which won’t be detailed in the full coupling map returned by [`coupling_map`](qiskit.providers.BackendV2#coupling_map "qiskit.providers.BackendV2.coupling_map"). So depending on your use case it might be necessary to look deeper than just the equivalent access with [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2"). + +Below is a table of example access patterns in [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") and the new form with [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2"): + +| [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") | [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") | Notes | +| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `backend.configuration().n_qubits` | `backend.num_qubits` | | +| `backend.configuration().coupling_map` | `backend.coupling_map` | The return from [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") is a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object. while in [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") it is an edge list. Also this is just a view of the information contained in `backend.target` which may only be a subset of the information contained in [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object. | +| `backend.configuration().backend_name` | `backend.name` | | +| `backend.configuration().backend_version` | `backend.backend_version` | The [`version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version") attribute represents the version of the abstract [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") interface the object implements while [`backend_version`](qiskit.providers.BackendV2#backend_version "qiskit.providers.BackendV2.backend_version") is metadata about the version of the backend itself. | +| `backend.configuration().basis_gates` | `backend.operation_names` | The [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") return is a list of operation names contained in the `backend.target` attribute. The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") may contain more information that can be expressed by this list of names. For example, that some operations only work on a subset of qubits or that some names implement the same gate with different parameters. | +| `backend.configuration().dt` | `backend.dt` | | +| `backend.configuration().dtm` | `backend.dtm` | | +| `backend.configuration().max_experiments` | `backend.max_circuits` | | +| `backend.configuration().online_date` | `backend.online_date` | | +| `InstructionDurations.from_backend(backend)` | `backend.instruction_durations` | | +| `backend.defaults().instruction_schedule_map` | `backend.instruction_schedule_map` | | +| `backend.properties().t1(0)` | `backend.qubit_properties(0).t1` | | +| `backend.properties().t2(0)` | `backend.qubit_properties(0).t2` | | +| `backend.properties().frequency(0)` | `backend.qubit_properties(0).frequency` | | +| `backend.properties().readout_error(0)` | `backend.target["measure"][(0,)].error` | In [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") the error rate for the [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure") operation on a given qubit is used to model the readout error. However a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") can implement multiple measurement types and list them separately in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"). | +| `backend.properties().readout_length(0)` | `backend.target["measure"][(0,)].duration` | In [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") the duration for the [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure") operation on a given qubit is used to model the readout length. However, a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") can implement multiple measurement types and list them separately in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"). | + +There is also a [`BackendV2Converter`](qiskit.providers.BackendV2Converter "qiskit.providers.BackendV2Converter") class available that enables you to wrap a [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") object with a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") interface. + diff --git a/docs/api/qiskit/0.46/providers_basic_provider.md b/docs/api/qiskit/0.46/providers_basic_provider.md new file mode 100644 index 00000000000..df53414332b --- /dev/null +++ b/docs/api/qiskit/0.46/providers_basic_provider.md @@ -0,0 +1,52 @@ +--- +title: basic_provider +description: API reference for qiskit.providers.basic_provider +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.providers.basic_provider +--- + + + + + + + +# BasicProvider: Python-based Simulators + + + +`qiskit.providers.basic_provider` + +A module of Python-based quantum simulators. Simulators can be accessed via the BasicProvider provider, e.g.: + +```python +from qiskit.providers.basic_provider import BasicProvider + +backend = BasicProvider().get_backend('basic_simulator') +``` + +## Simulators + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator")(\[provider, target]) | Python implementation of a basic (non-efficient) quantum simulator. | + +## Provider + +| | | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------- | +| [`BasicProvider`](qiskit.providers.basic_provider.BasicProvider "qiskit.providers.basic_provider.BasicProvider")() | Provider for test simulators. | + +## Job Class + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [`BasicProviderJob`](qiskit.providers.basic_provider.BasicProviderJob "qiskit.providers.basic_provider.BasicProviderJob")(backend, job\_id, result) | BasicProviderJob class. | + +## Exceptions + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | +| [`BasicProviderError`](qiskit.providers.basic_provider.BasicProviderError "qiskit.providers.basic_provider.BasicProviderError")(\*message) | Base class for errors raised by the Basic Provider. | + diff --git a/docs/api/qiskit/0.46/providers_basicaer.md b/docs/api/qiskit/0.46/providers_basicaer.md new file mode 100644 index 00000000000..086ed85ad18 --- /dev/null +++ b/docs/api/qiskit/0.46/providers_basicaer.md @@ -0,0 +1,58 @@ +--- +title: basicaer +description: API reference for qiskit.providers.basicaer +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.providers.basicaer +--- + + + + + + + +# BasicAer: Python-based Simulators + + + +`qiskit.providers.basicaer` + + + The [`qiskit.providers.basicaer`](#module-qiskit.providers.basicaer "qiskit.providers.basicaer") module is deprecated as of Qiskit 0.46 and will be removed in Qiskit 1.0. Its functionality has been replaced by the new [`qiskit.providers.basic_provider`](providers_basic_provider#module-qiskit.providers.basic_provider "qiskit.providers.basic_provider") module and the [`qiskit.quantum_info`](quantum_info#module-qiskit.quantum_info "qiskit.quantum_info") module. + + +A module of Python-based quantum simulators. Simulators are accessed via the BasicAer provider, e.g.: + +```python +from qiskit import BasicAer + +backend = BasicAer.get_backend('qasm_simulator') +``` + +## Simulators + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| [`QasmSimulatorPy`](qiskit.providers.basicaer.QasmSimulatorPy "qiskit.providers.basicaer.QasmSimulatorPy")(\[configuration, provider]) | Python implementation of an OpenQASM 2 simulator. | +| [`StatevectorSimulatorPy`](qiskit.providers.basicaer.StatevectorSimulatorPy "qiskit.providers.basicaer.StatevectorSimulatorPy")(\[configuration, provider]) | Python statevector simulator. | +| [`UnitarySimulatorPy`](qiskit.providers.basicaer.UnitarySimulatorPy "qiskit.providers.basicaer.UnitarySimulatorPy")(\[configuration, provider]) | Python implementation of a unitary simulator. | + +## Provider + +| | | +| --------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| [`BasicAerProvider`](qiskit.providers.basicaer.BasicAerProvider "qiskit.providers.basicaer.BasicAerProvider")() | Provider for Basic Aer backends. | + +## Job Class + +| | | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------ | +| [`BasicAerJob`](qiskit.providers.basicaer.BasicAerJob "qiskit.providers.basicaer.BasicAerJob")(backend, job\_id, result) | BasicAerJob class. | + +## Exceptions + +| | | +| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| [`BasicAerError`](qiskit.providers.basicaer.BasicAerError "qiskit.providers.basicaer.BasicAerError")(\*message) | Base class for errors raised by Basic Aer. | + diff --git a/docs/api/qiskit/0.46/providers_fake_provider.md b/docs/api/qiskit/0.46/providers_fake_provider.md new file mode 100644 index 00000000000..e03e312b370 --- /dev/null +++ b/docs/api/qiskit/0.46/providers_fake_provider.md @@ -0,0 +1,265 @@ +--- +title: fake_provider +description: API reference for qiskit.providers.fake_provider +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.providers.fake_provider +--- + + + + + + + +# Fake Provider + + + +`qiskit.providers.fake_provider` + +## Overview + +The fake provider module contains fake providers, fake backends and other simulated backend implementations. The fake backends are built to mimic the behaviors of IBM Quantum systems using system snapshots. The system snapshots contain important information about the quantum system such as coupling map, basis gates, qubit properties (T1, T2, error rate, etc.) which are useful for testing the transpiler and performing noisy simulation of the system. + +## Example Usage + +Here is an example of using a fake backend for transpilation and simulation. + +```python +from qiskit import QuantumCircuit +from qiskit.providers.fake_provider import FakeManilaV2 +from qiskit import transpile +from qiskit.tools.visualization import plot_histogram + + +# Get a fake backend from the fake provider +backend = FakeManilaV2() + +# Create a simple circuit +circuit = QuantumCircuit(3) +circuit.h(0) +circuit.cx(0,1) +circuit.cx(0,2) +circuit.measure_all() +circuit.draw('mpl') + +# Transpile the ideal circuit to a circuit that can be directly executed by the backend +transpiled_circuit = transpile(circuit, backend) +transpiled_circuit.draw('mpl') + +# Run the transpiled circuit using the simulated fake backend +job = backend.run(transpiled_circuit) +counts = job.result().get_counts() +plot_histogram(counts) +``` + +![../\_images/providers\_fake\_provider-1\_00.png](/images/api/qiskit/0.46/providers_fake_provider-1_00.png) + +![../\_images/providers\_fake\_provider-1\_01.png](/images/api/qiskit/0.46/providers_fake_provider-1_01.png) + +![../\_images/providers\_fake\_provider-1\_02.png](/images/api/qiskit/0.46/providers_fake_provider-1_02.png) + + + Please note that the simulation is done using a noise model generated from system snapshots obtained in the past (sometimes a few years ago) and the results are not representative of the latest behaviours of the real quantum system which the fake backend is mimicking. If you want to run noisy simulations to compare with the real quantum system, please follow steps below to generate a simulator mimics a real quantum system with the latest calibration results. + + ```python + from qiskit.providers.ibmq import IBMQ + from qiskit_aer import AerSimulator + + # get a real backend from a real provider + provider = IBMQ.load_account() + backend = provider.get_backend('ibmq_manila') + + # generate a simulator that mimics the real quantum system with the latest calibration results + backend_sim = AerSimulator.from_backend(backend) + ``` + + +## Fake Providers + +Fake providers provide access to a list of fake backends. + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| [`FakeProviderForBackendV2`](qiskit.providers.fake_provider.FakeProviderForBackendV2 "qiskit.providers.fake_provider.FakeProviderForBackendV2")() | Fake provider containing fake V2 backends. | +| [`FakeProvider`](qiskit.providers.fake_provider.FakeProvider "qiskit.providers.fake_provider.FakeProvider")() | Fake provider containing fake V1 backends. | + +## Fake Backends + +### Fake V2 Backends + +Fake V2 backends are fake backends with IBM Quantum systems snapshots implemented with [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") interface. They are all subclasses of [`FakeBackendV2`](qiskit.providers.fake_provider.FakeBackendV2 "qiskit.providers.fake_provider.FakeBackendV2"). + +| | | +| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| [`FakeAlmadenV2`](qiskit.providers.fake_provider.FakeAlmadenV2 "qiskit.providers.fake_provider.FakeAlmadenV2")() | A fake Almaden V2 backend. | +| [`FakeArmonkV2`](qiskit.providers.fake_provider.FakeArmonkV2 "qiskit.providers.fake_provider.FakeArmonkV2")() | A fake 1 qubit backend. | +| [`FakeAthensV2`](qiskit.providers.fake_provider.FakeAthensV2 "qiskit.providers.fake_provider.FakeAthensV2")() | A fake 5 qubit backend. | +| [`FakeAuckland`](qiskit.providers.fake_provider.FakeAuckland "qiskit.providers.fake_provider.FakeAuckland")() | A fake 27 qubit backend. | +| [`FakeBelemV2`](qiskit.providers.fake_provider.FakeBelemV2 "qiskit.providers.fake_provider.FakeBelemV2")() | A fake 5 qubit backend. | +| [`FakeBoeblingenV2`](qiskit.providers.fake_provider.FakeBoeblingenV2 "qiskit.providers.fake_provider.FakeBoeblingenV2")() | A fake Boeblingen V2 backend. | +| [`FakeBogotaV2`](qiskit.providers.fake_provider.FakeBogotaV2 "qiskit.providers.fake_provider.FakeBogotaV2")() | A fake 5 qubit backend. | +| [`FakeBrooklynV2`](qiskit.providers.fake_provider.FakeBrooklynV2 "qiskit.providers.fake_provider.FakeBrooklynV2")() | A fake Brooklyn V2 backend. | +| [`FakeBurlingtonV2`](qiskit.providers.fake_provider.FakeBurlingtonV2 "qiskit.providers.fake_provider.FakeBurlingtonV2")() | A fake 5 qubit backend. | +| [`FakeCairoV2`](qiskit.providers.fake_provider.FakeCairoV2 "qiskit.providers.fake_provider.FakeCairoV2")() | A fake 27 qubit backend. | +| [`FakeCambridgeV2`](qiskit.providers.fake_provider.FakeCambridgeV2 "qiskit.providers.fake_provider.FakeCambridgeV2")() | A fake Cambridge backend. | +| [`FakeCasablancaV2`](qiskit.providers.fake_provider.FakeCasablancaV2 "qiskit.providers.fake_provider.FakeCasablancaV2")() | A fake 7 qubit backend. | +| [`FakeEssexV2`](qiskit.providers.fake_provider.FakeEssexV2 "qiskit.providers.fake_provider.FakeEssexV2")() | A fake 5 qubit backend. | +| [`FakeGeneva`](qiskit.providers.fake_provider.FakeGeneva "qiskit.providers.fake_provider.FakeGeneva")() | A fake 27 qubit backend. | +| [`FakeGuadalupeV2`](qiskit.providers.fake_provider.FakeGuadalupeV2 "qiskit.providers.fake_provider.FakeGuadalupeV2")() | A fake 16 qubit backend. | +| [`FakeHanoiV2`](qiskit.providers.fake_provider.FakeHanoiV2 "qiskit.providers.fake_provider.FakeHanoiV2")() | A fake 27 qubit backend. | +| [`FakeJakartaV2`](qiskit.providers.fake_provider.FakeJakartaV2 "qiskit.providers.fake_provider.FakeJakartaV2")() | A fake 7 qubit V2 backend. | +| [`FakeJohannesburgV2`](qiskit.providers.fake_provider.FakeJohannesburgV2 "qiskit.providers.fake_provider.FakeJohannesburgV2")() | A fake Johannesburg V2 backend. | +| [`FakeKolkataV2`](qiskit.providers.fake_provider.FakeKolkataV2 "qiskit.providers.fake_provider.FakeKolkataV2")() | A fake 27 qubit backend. | +| [`FakeLagosV2`](qiskit.providers.fake_provider.FakeLagosV2 "qiskit.providers.fake_provider.FakeLagosV2")() | A fake 7 qubit backend. | +| [`FakeLimaV2`](qiskit.providers.fake_provider.FakeLimaV2 "qiskit.providers.fake_provider.FakeLimaV2")() | A fake 5 qubit backend. | +| [`FakeLondonV2`](qiskit.providers.fake_provider.FakeLondonV2 "qiskit.providers.fake_provider.FakeLondonV2")() | A fake 5 qubit backend. | +| [`FakeManhattanV2`](qiskit.providers.fake_provider.FakeManhattanV2 "qiskit.providers.fake_provider.FakeManhattanV2")() | A fake Manhattan backend. | +| [`FakeManilaV2`](qiskit.providers.fake_provider.FakeManilaV2 "qiskit.providers.fake_provider.FakeManilaV2")() | A fake 5 qubit backend. | +| [`FakeMelbourneV2`](qiskit.providers.fake_provider.FakeMelbourneV2 "qiskit.providers.fake_provider.FakeMelbourneV2")() | A fake 14 qubit backend. | +| [`FakeMontrealV2`](qiskit.providers.fake_provider.FakeMontrealV2 "qiskit.providers.fake_provider.FakeMontrealV2")() | A fake 27 qubit backend. | +| [`FakeMumbaiV2`](qiskit.providers.fake_provider.FakeMumbaiV2 "qiskit.providers.fake_provider.FakeMumbaiV2")() | A fake 27 qubit backend. | +| [`FakeNairobiV2`](qiskit.providers.fake_provider.FakeNairobiV2 "qiskit.providers.fake_provider.FakeNairobiV2")() | A fake 7 qubit backend. | +| [`FakeOslo`](qiskit.providers.fake_provider.FakeOslo "qiskit.providers.fake_provider.FakeOslo")() | A fake 7 qubit backend. | +| [`FakeOurenseV2`](qiskit.providers.fake_provider.FakeOurenseV2 "qiskit.providers.fake_provider.FakeOurenseV2")() | A fake 5 qubit backend. | +| [`FakeParisV2`](qiskit.providers.fake_provider.FakeParisV2 "qiskit.providers.fake_provider.FakeParisV2")() | A fake Paris backend. | +| [`FakePerth`](qiskit.providers.fake_provider.FakePerth "qiskit.providers.fake_provider.FakePerth")() | A fake 7 qubit backend. | +| [`FakePrague`](qiskit.providers.fake_provider.FakePrague "qiskit.providers.fake_provider.FakePrague")() | A fake 33 qubit backend. | +| [`FakePoughkeepsieV2`](qiskit.providers.fake_provider.FakePoughkeepsieV2 "qiskit.providers.fake_provider.FakePoughkeepsieV2")() | A fake Poughkeepsie backend. | +| [`FakeQuitoV2`](qiskit.providers.fake_provider.FakeQuitoV2 "qiskit.providers.fake_provider.FakeQuitoV2")() | A fake 5 qubit backend. | +| [`FakeRochesterV2`](qiskit.providers.fake_provider.FakeRochesterV2 "qiskit.providers.fake_provider.FakeRochesterV2")() | A fake Rochester backend. | +| [`FakeRomeV2`](qiskit.providers.fake_provider.FakeRomeV2 "qiskit.providers.fake_provider.FakeRomeV2")() | A fake 5 qubit backend. | +| [`FakeSantiagoV2`](qiskit.providers.fake_provider.FakeSantiagoV2 "qiskit.providers.fake_provider.FakeSantiagoV2")() | A fake Santiago backend. | +| [`FakeSherbrooke`](qiskit.providers.fake_provider.FakeSherbrooke "qiskit.providers.fake_provider.FakeSherbrooke")() | A fake 127 qubit backend. | +| [`FakeSingaporeV2`](qiskit.providers.fake_provider.FakeSingaporeV2 "qiskit.providers.fake_provider.FakeSingaporeV2")() | A fake Singapore backend. | +| [`FakeSydneyV2`](qiskit.providers.fake_provider.FakeSydneyV2 "qiskit.providers.fake_provider.FakeSydneyV2")() | A fake 27 qubit backend. | +| [`FakeTorontoV2`](qiskit.providers.fake_provider.FakeTorontoV2 "qiskit.providers.fake_provider.FakeTorontoV2")() | A fake 27 qubit backend. | +| [`FakeValenciaV2`](qiskit.providers.fake_provider.FakeValenciaV2 "qiskit.providers.fake_provider.FakeValenciaV2")() | A fake 5 qubit backend. | +| [`FakeVigoV2`](qiskit.providers.fake_provider.FakeVigoV2 "qiskit.providers.fake_provider.FakeVigoV2")() | A fake 5 qubit backend. | +| [`FakeWashingtonV2`](qiskit.providers.fake_provider.FakeWashingtonV2 "qiskit.providers.fake_provider.FakeWashingtonV2")() | A fake 127 qubit backend. | +| [`FakeYorktownV2`](qiskit.providers.fake_provider.FakeYorktownV2 "qiskit.providers.fake_provider.FakeYorktownV2")() | A fake 5 qubit backend. | + +### Fake V1 Backends + +Fake V1 backends are fake backends with IBM Quantum systems snapshots implemented with [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.backend.BackendV1") interface. + +| | | +| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| [`FakeAlmaden`](qiskit.providers.fake_provider.FakeAlmaden "qiskit.providers.fake_provider.FakeAlmaden")() | A fake Almaden backend. | +| [`FakeArmonk`](qiskit.providers.fake_provider.FakeArmonk "qiskit.providers.fake_provider.FakeArmonk")() | A fake 1 qubit backend. | +| [`FakeAthens`](qiskit.providers.fake_provider.FakeAthens "qiskit.providers.fake_provider.FakeAthens")() | A fake 5 qubit backend. | +| [`FakeBelem`](qiskit.providers.fake_provider.FakeBelem "qiskit.providers.fake_provider.FakeBelem")() | A fake 5 qubit backend. | +| [`FakeBoeblingen`](qiskit.providers.fake_provider.FakeBoeblingen "qiskit.providers.fake_provider.FakeBoeblingen")() | A fake Boeblingen backend. | +| [`FakeBogota`](qiskit.providers.fake_provider.FakeBogota "qiskit.providers.fake_provider.FakeBogota")() | A fake 5 qubit backend. | +| [`FakeBrooklyn`](qiskit.providers.fake_provider.FakeBrooklyn "qiskit.providers.fake_provider.FakeBrooklyn")() | A fake Brooklyn backend. | +| [`FakeBurlington`](qiskit.providers.fake_provider.FakeBurlington "qiskit.providers.fake_provider.FakeBurlington")() | A fake 5 qubit backend. | +| [`FakeCairo`](qiskit.providers.fake_provider.FakeCairo "qiskit.providers.fake_provider.FakeCairo")() | A fake 27 qubit backend. | +| [`FakeCambridge`](qiskit.providers.fake_provider.FakeCambridge "qiskit.providers.fake_provider.FakeCambridge")() | A fake Cambridge backend. | +| [`FakeCasablanca`](qiskit.providers.fake_provider.FakeCasablanca "qiskit.providers.fake_provider.FakeCasablanca")() | A fake 7 qubit backend. | +| [`FakeEssex`](qiskit.providers.fake_provider.FakeEssex "qiskit.providers.fake_provider.FakeEssex")() | A fake 5 qubit backend. | +| [`FakeGuadalupe`](qiskit.providers.fake_provider.FakeGuadalupe "qiskit.providers.fake_provider.FakeGuadalupe")() | A fake 16 qubit backend. | +| [`FakeHanoi`](qiskit.providers.fake_provider.FakeHanoi "qiskit.providers.fake_provider.FakeHanoi")() | A fake 27 qubit backend. | +| [`FakeJakarta`](qiskit.providers.fake_provider.FakeJakarta "qiskit.providers.fake_provider.FakeJakarta")() | A fake 7 qubit backend. | +| [`FakeJohannesburg`](qiskit.providers.fake_provider.FakeJohannesburg "qiskit.providers.fake_provider.FakeJohannesburg")() | A fake Johannesburg backend. | +| [`FakeKolkata`](qiskit.providers.fake_provider.FakeKolkata "qiskit.providers.fake_provider.FakeKolkata")() | A fake 27 qubit backend. | +| [`FakeLagos`](qiskit.providers.fake_provider.FakeLagos "qiskit.providers.fake_provider.FakeLagos")() | A fake 7 qubit backend. | +| [`FakeLima`](qiskit.providers.fake_provider.FakeLima "qiskit.providers.fake_provider.FakeLima")() | A fake 5 qubit backend. | +| [`FakeLondon`](qiskit.providers.fake_provider.FakeLondon "qiskit.providers.fake_provider.FakeLondon")() | A fake 5 qubit backend. | +| [`FakeManhattan`](qiskit.providers.fake_provider.FakeManhattan "qiskit.providers.fake_provider.FakeManhattan")() | A fake Manhattan backend. | +| [`FakeManila`](qiskit.providers.fake_provider.FakeManila "qiskit.providers.fake_provider.FakeManila")() | A fake 5 qubit backend. | +| [`FakeMelbourne`](qiskit.providers.fake_provider.FakeMelbourne "qiskit.providers.fake_provider.FakeMelbourne")() | A fake 14 qubit backend. | +| [`FakeMontreal`](qiskit.providers.fake_provider.FakeMontreal "qiskit.providers.fake_provider.FakeMontreal")() | A fake 27 qubit backend. | +| [`FakeMumbai`](qiskit.providers.fake_provider.FakeMumbai "qiskit.providers.fake_provider.FakeMumbai")() | A fake 27 qubit backend. | +| [`FakeNairobi`](qiskit.providers.fake_provider.FakeNairobi "qiskit.providers.fake_provider.FakeNairobi")() | A fake 7 qubit backend. | +| [`FakeOurense`](qiskit.providers.fake_provider.FakeOurense "qiskit.providers.fake_provider.FakeOurense")() | A fake 5 qubit backend. | +| [`FakeParis`](qiskit.providers.fake_provider.FakeParis "qiskit.providers.fake_provider.FakeParis")() | A fake Paris backend. | +| [`FakePoughkeepsie`](qiskit.providers.fake_provider.FakePoughkeepsie "qiskit.providers.fake_provider.FakePoughkeepsie")() | A fake Poughkeepsie backend. | +| [`FakeQuito`](qiskit.providers.fake_provider.FakeQuito "qiskit.providers.fake_provider.FakeQuito")() | A fake 5 qubit backend. | +| [`FakeRochester`](qiskit.providers.fake_provider.FakeRochester "qiskit.providers.fake_provider.FakeRochester")() | A fake Rochester backend. | +| [`FakeRome`](qiskit.providers.fake_provider.FakeRome "qiskit.providers.fake_provider.FakeRome")() | A fake 5 qubit backend. | +| [`FakeRueschlikon`](qiskit.providers.fake_provider.FakeRueschlikon "qiskit.providers.fake_provider.FakeRueschlikon")() | A fake 16 qubit backend. | +| [`FakeSantiago`](qiskit.providers.fake_provider.FakeSantiago "qiskit.providers.fake_provider.FakeSantiago")() | A fake Santiago backend. | +| [`FakeSingapore`](qiskit.providers.fake_provider.FakeSingapore "qiskit.providers.fake_provider.FakeSingapore")() | A fake Singapore backend. | +| [`FakeSydney`](qiskit.providers.fake_provider.FakeSydney "qiskit.providers.fake_provider.FakeSydney")() | A fake 27 qubit backend. | +| [`FakeTenerife`](qiskit.providers.fake_provider.FakeTenerife "qiskit.providers.fake_provider.FakeTenerife")() | A fake 5 qubit backend. | +| [`FakeTokyo`](qiskit.providers.fake_provider.FakeTokyo "qiskit.providers.fake_provider.FakeTokyo")() | A fake 20 qubit backend. | +| [`FakeToronto`](qiskit.providers.fake_provider.FakeToronto "qiskit.providers.fake_provider.FakeToronto")() | A fake 27 qubit backend. | +| [`FakeValencia`](qiskit.providers.fake_provider.FakeValencia "qiskit.providers.fake_provider.FakeValencia")() | A fake 5 qubit backend. | +| [`FakeVigo`](qiskit.providers.fake_provider.FakeVigo "qiskit.providers.fake_provider.FakeVigo")() | A fake 5 qubit backend. | +| [`FakeWashington`](qiskit.providers.fake_provider.FakeWashington "qiskit.providers.fake_provider.FakeWashington")() | A fake 127 qubit backend. | +| [`FakeYorktown`](qiskit.providers.fake_provider.FakeYorktown "qiskit.providers.fake_provider.FakeYorktown")() | A fake 5 qubit backend. | + +## Special Fake Backends + +Special fake backends are fake backends that were created for special testing purposes. + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| [`FakeQasmSimulator`](qiskit.providers.fake_provider.FakeQasmSimulator "qiskit.providers.fake_provider.FakeQasmSimulator")() | A fake simulator backend. | +| [`FakeOpenPulse2Q`](qiskit.providers.fake_provider.FakeOpenPulse2Q "qiskit.providers.fake_provider.FakeOpenPulse2Q")() | A fake 2 qubit backend for pulse test. | +| [`FakeOpenPulse3Q`](qiskit.providers.fake_provider.FakeOpenPulse3Q "qiskit.providers.fake_provider.FakeOpenPulse3Q")() | Trivial extension of the FakeOpenPulse2Q. | +| [`Fake1Q`](qiskit.providers.fake_provider.Fake1Q "qiskit.providers.fake_provider.Fake1Q")() | A fake 1Q backend. | +| [`FakeBackendV2`](qiskit.providers.fake_provider.FakeBackendV2 "qiskit.providers.fake_provider.FakeBackendV2")() | A mock backend that doesn't implement run() to test compatibility with Terra internals. | +| [`FakeBackend5QV2`](qiskit.providers.fake_provider.FakeBackend5QV2 "qiskit.providers.fake_provider.FakeBackend5QV2")(\[bidirectional]) | A mock backend that doesn't implement run() to test compatibility with Terra internals. | +| [`FakeMumbaiFractionalCX`](qiskit.providers.fake_provider.FakeMumbaiFractionalCX "qiskit.providers.fake_provider.FakeMumbaiFractionalCX")() | A fake mumbai backend. | +| [`ConfigurableFakeBackend`](qiskit.providers.fake_provider.ConfigurableFakeBackend "qiskit.providers.fake_provider.ConfigurableFakeBackend")(name, n\_qubits\[, ...]) | Configurable backend. | +| [`GenericBackendV2`](qiskit.providers.fake_provider.GenericBackendV2 "qiskit.providers.fake_provider.GenericBackendV2")(num\_qubits\[, basis\_gates, ...]) | Generic [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") implementation with a configurable constructor. | + +## Fake Backend Base Classes + +The fake backends based on IBM hardware are based on a set of base classes: + + + +`qiskit.providers.fake_provider.fake_backend.FakeBackendV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_backend.py "view source code") + +A fake backend class for testing and noisy simulation using real backend snapshots. + +The class inherits [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") class. This version differs from earlier [`FakeBackend`](#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.FakeBackend") (V1) class in a few aspects. Firstly, configuration attribute no longer exists. Instead, attributes exposing equivalent required immutable properties of the backend device are added. For example `fake_backend.configuration().n_qubits` is accessible from `fake_backend.num_qubits` now. Secondly, this version removes extra abstractions [`FakeQasmBackend`](#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.FakeQasmBackend") and [`FakePulseBackend`](#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.FakePulseBackend") that were present in V1. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + + + +`qiskit.providers.fake_provider.FakeBackend(configuration, time_alive=10)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_backend.py "view source code") + +This is a dummy backend just for testing purposes. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + + + +`qiskit.providers.fake_provider.FakeQasmBackend`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_qasm_backend.py "view source code") + +A fake OpenQASM backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + + + +`qiskit.providers.fake_provider.FakePulseBackend`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_pulse_backend.py "view source code") + +A fake pulse backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + diff --git a/docs/api/qiskit/0.46/providers_models.md b/docs/api/qiskit/0.46/providers_models.md new file mode 100644 index 00000000000..0816d353708 --- /dev/null +++ b/docs/api/qiskit/0.46/providers_models.md @@ -0,0 +1,39 @@ +--- +title: models +description: API reference for qiskit.providers.models +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.providers.models +--- + + + + + + + +# Backend Objects + + + +`qiskit.providers.models` + +Qiskit schema-conformant objects used by the backends and providers. + +## Backend Objects + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [`BackendConfiguration`](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")(backend\_name, ...\[, ...]) | Backwards compat shim representing an abstract backend configuration. | +| [`BackendProperties`](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")(backend\_name, ...) | Class representing backend properties | +| [`BackendStatus`](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus")(backend\_name, backend\_version, ...) | Class representing Backend Status. | +| [`QasmBackendConfiguration`](qiskit.providers.models.QasmBackendConfiguration "qiskit.providers.models.QasmBackendConfiguration")(backend\_name, ...) | Class representing an OpenQASM 2.0 Backend Configuration. | +| [`PulseBackendConfiguration`](qiskit.providers.models.PulseBackendConfiguration "qiskit.providers.models.PulseBackendConfiguration")(backend\_name, ...) | Static configuration state for an OpenPulse enabled backend. | +| [`UchannelLO`](qiskit.providers.models.UchannelLO "qiskit.providers.models.UchannelLO")(q, scale) | Class representing a U Channel LO | +| [`GateConfig`](qiskit.providers.models.GateConfig "qiskit.providers.models.GateConfig")(name, parameters, qasm\_def\[, ...]) | Class representing a Gate Configuration | +| [`PulseDefaults`](qiskit.providers.models.PulseDefaults "qiskit.providers.models.PulseDefaults")(qubit\_freq\_est, meas\_freq\_est, ...) | Description of default settings for Pulse systems. | +| [`Command`](qiskit.providers.models.Command "qiskit.providers.models.Command")(name\[, qubits, sequence]) | Class representing a Command. | +| [`JobStatus`](qiskit.providers.models.JobStatus "qiskit.providers.models.JobStatus")(job\_id, status, status\_msg, \*\*kwargs) | Model for JobStatus. | +| [`GateProperties`](qiskit.providers.models.GateProperties "qiskit.providers.models.GateProperties")(qubits, gate, parameters, ...) | Class representing a gate's properties | +| [`Nduv`](qiskit.providers.models.Nduv "qiskit.providers.models.Nduv")(date, name, unit, value) | Class representing name-date-unit-value | + diff --git a/docs/api/qiskit/0.46/pulse.md b/docs/api/qiskit/0.46/pulse.md new file mode 100644 index 00000000000..5ffda402d4f --- /dev/null +++ b/docs/api/qiskit/0.46/pulse.md @@ -0,0 +1,2798 @@ +--- +title: pulse +description: API reference for qiskit.pulse +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.pulse +--- + + + + + + + +# Pulse + + + +`qiskit.pulse` + +Qiskit-Pulse is a pulse-level quantum programming kit. This lower level of programming offers the user more control than programming with [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")s. + +Extracting the greatest performance from quantum hardware requires real-time pulse-level instructions. Pulse answers that need: it enables the quantum physicist *user* to specify the exact time dynamics of an experiment. It is especially powerful for error mitigation techniques. + +The input is given as arbitrary, time-ordered signals (see: [Instructions](#pulse-insts)) scheduled in parallel over multiple virtual hardware or simulator resources (see: [Channels](#pulse-channels)). The system also allows the user to recover the time dynamics of the measured output. + +This is sufficient to allow the quantum physicist to explore and correct for noise in a quantum system. + + + + + + + +## Instructions + + + +`qiskit.pulse.instructions` + +The `instructions` module holds the various [`Instruction`](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.Instruction")s which are supported by Qiskit Pulse. Instructions have operands, which typically include at least one [`Channel`](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") specifying where the instruction will be applied. + +Every instruction has a duration, whether explicitly included as an operand or implicitly defined. For instance, a [`ShiftPhase`](qiskit.pulse.instructions.ShiftPhase "qiskit.pulse.instructions.ShiftPhase") instruction can be instantiated with operands *phase* and *channel*, for some float `phase` and a [`Channel`](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") `channel`: + +```python +ShiftPhase(phase, channel) +``` + +The duration of this instruction is implicitly zero. On the other hand, the [`Delay`](qiskit.pulse.instructions.Delay "qiskit.pulse.instructions.Delay") instruction takes an explicit duration: + +```python +Delay(duration, channel) +``` + +An instruction can be added to a [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"), which is a sequence of scheduled Pulse `Instruction` s over many channels. `Instruction` s and `Schedule` s implement the same interface. + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Acquire`](qiskit.pulse.instructions.Acquire "qiskit.pulse.instructions.Acquire")(duration, channel\[, mem\_slot, ...]) | The Acquire instruction is used to trigger the ADC associated with a particular qubit; e.g. | +| [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call")(subroutine\[, value\_dict, name]) | Pulse `Call` instruction. | +| [`Reference`](qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference")(name, \*extra\_keys) | Pulse compiler directive that refers to a subroutine. | +| [`Delay`](qiskit.pulse.instructions.Delay "qiskit.pulse.instructions.Delay")(duration, channel\[, name]) | A blocking instruction with no other effect. | +| [`Play`](qiskit.pulse.instructions.Play "qiskit.pulse.instructions.Play")(pulse, channel\[, name]) | This instruction is responsible for applying a pulse on a channel. | +| [`RelativeBarrier`](qiskit.pulse.instructions.RelativeBarrier "qiskit.pulse.instructions.RelativeBarrier")(\*channels\[, name]) | Pulse `RelativeBarrier` directive. | +| [`SetFrequency`](qiskit.pulse.instructions.SetFrequency "qiskit.pulse.instructions.SetFrequency")(frequency, channel\[, name]) | Set the channel frequency. | +| [`ShiftFrequency`](qiskit.pulse.instructions.ShiftFrequency "qiskit.pulse.instructions.ShiftFrequency")(frequency, channel\[, name]) | Shift the channel frequency away from the current frequency. | +| [`SetPhase`](qiskit.pulse.instructions.SetPhase "qiskit.pulse.instructions.SetPhase")(phase, channel\[, name]) | The set phase instruction sets the phase of the proceeding pulses on that channel to `phase` radians. | +| [`ShiftPhase`](qiskit.pulse.instructions.ShiftPhase "qiskit.pulse.instructions.ShiftPhase")(phase, channel\[, name]) | The shift phase instruction updates the modulation phase of proceeding pulses played on the same [`Channel`](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel"). | +| [`Snapshot`](qiskit.pulse.instructions.Snapshot "qiskit.pulse.instructions.Snapshot")(label\[, snapshot\_type, name]) | An instruction targeted for simulators, to capture a moment in the simulation. | +| [`TimeBlockade`](qiskit.pulse.instructions.TimeBlockade "qiskit.pulse.instructions.TimeBlockade")(duration, channel\[, name]) | Pulse `TimeBlockade` directive. | + +These are all instances of the same base class: + + + +`qiskit.pulse.instructions.Instruction(operands, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/instruction.py "view source code") + +The smallest schedulable unit: a single instruction. It has a fixed duration and specified channels. + +Instruction initializer. + +**Parameters** + +* **operands** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")) – The argument list. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Optional display name for this instruction. + + + + + +## Pulse Library + + + +`qiskit.pulse.library` + +This library provides Pulse users with convenient methods to build Pulse waveforms. + +A pulse programmer can choose from one of several [Pulse Models](#pulse-models) such as [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform") and [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") to create a pulse program. The [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform") model directly stores the waveform data points in each class instance. This model provides the most flexibility to express arbitrary waveforms and allows a rapid prototyping of new control techniques. However, this model is typically memory inefficient and might be hard to scale to large-size quantum processors. Several waveform subclasses are defined by [Waveform Pulse Representation](#waveforms), but a user can also directly instantiate the [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform") class with `samples` argument which is usually a complex numpy array or any kind of array-like data. + +In contrast, the [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") model only stores the function and its parameters that generate the waveform in a class instance. It thus provides greater memory efficiency at the price of less flexibility in the waveform. This model also defines a small set of pulse subclasses in [Parametric Pulse Representation](#symbolic-pulses) which are commonly used in superconducting quantum processors. An instance of these subclasses can be serialized in the [QPY Format](qpy#qpy-format) while keeping the memory-efficient parametric representation of waveforms. Note that [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform") object can be generated from an instance of a [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") which will set values for the parameters and sample the parametric expression to create the [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + + + +### Pulse Models + +| | | +| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform")(samples\[, name, epsilon, ...]) | A pulse specified completely by complex-valued samples; each sample is played for the duration of the backend cycle-time, dt. | +| [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse")(pulse\_type, duration\[, ...]) | The pulse representation model with parameters and symbolic expressions. | +| [`ParametricPulse`](qiskit.pulse.library.ParametricPulse "qiskit.pulse.library.ParametricPulse")(duration\[, name, ...]) | The abstract superclass for parametric pulses. | + + + +### Waveform Pulse Representation + +### constant + + + +`qiskit.pulse.library.constant(duration, amp, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates constant-sampled [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, samples from the function: + +$$ +f(x) = A +$$ + + + The function `qiskit.pulse.library.discrete.constant()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including constant() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Constant(…).get\_waveform(). Note that complex value support for the amp parameter is deprecated in the SymbolicPulse library. Use two float values for (amp, angle) instead of complex amp + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Complex pulse amplitude. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### zero + + + +`qiskit.pulse.library.zero(duration, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates zero-sampled [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +Samples from the function: + +$$ +f(x) = 0 +$$ + + + The function `qiskit.pulse.library.discrete.zero()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including zero() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Constant(amp=0,…).get\_waveform(). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### square + + + +`qiskit.pulse.library.square(duration, amp, freq=None, phase=0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates square wave [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, $T=$ `period`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = A \text{sign}\left[ \sin\left(\frac{2 \pi x}{T} + 2\phi\right) \right] +$$ + +with the convention $\text{sign}(0) = 1$. + + + The function `qiskit.pulse.library.discrete.square()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including square() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Square(…).get\_waveform(). Note that pulse.Square() does not support complex values for amp, and that the phase is defined differently. See documentation. + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude. Wave range is $[-$ `amp` $,$ `amp` $]$. +* **freq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse frequency, units of 1./dt. If `None` defaults to 1./duration. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse phase. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### sawtooth + + + +`qiskit.pulse.library.sawtooth(duration, amp, freq=None, phase=0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates sawtooth wave [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, $T=$ `period`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = 2 A \left( g(x) - \left\lfloor \frac{1}{2} + g(x) \right\rfloor\right) +$$ + +where $g(x) = x/T + \phi/\pi$. + + + The function `qiskit.pulse.library.discrete.sawtooth()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including sawtooth() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Sawtooth(…).get\_waveform(). Note that pulse.Sawtooth() does not support complex values for amp. Instead, use two float values for (amp, angle). Also note that the phase is defined differently, such that 2\*pi phase shifts by a full cycle. + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude. Wave range is $[-$ `amp` $,$ `amp` $]$. +* **freq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse frequency, units of 1./dt. If `None` defaults to 1./duration. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse phase. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +**Example** + +```python +import matplotlib.pyplot as plt +from qiskit.pulse.library import sawtooth +import numpy as np + +duration = 100 +amp = 1 +freq = 1 / duration +sawtooth_wave = np.real(sawtooth(duration, amp, freq).samples) +plt.plot(range(duration), sawtooth_wave) +plt.show() +``` + +![../\_images/pulse-1.png](/images/api/qiskit/0.46/pulse-1.png) + +### triangle + + + +`qiskit.pulse.library.triangle(duration, amp, freq=None, phase=0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates triangle wave [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, $T=$ `period`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = A \left(-2\left|\text{sawtooth}(x, A, T, \phi)\right| + 1\right) +$$ + +This a non-sinusoidal wave with linear ramping. + + + The function `qiskit.pulse.library.discrete.triangle()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including triangle() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Triangle(…).get\_waveform(). Note that pulse.Triangle() does not support complex values for amp. Instead, use two float values for (amp, angle). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude. Wave range is $[-$ `amp` $,$ `amp` $]$. +* **freq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse frequency, units of 1./dt. If `None` defaults to 1./duration. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse phase. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +**Example** + +```python +import matplotlib.pyplot as plt +from qiskit.pulse.library import triangle +import numpy as np + +duration = 100 +amp = 1 +freq = 1 / duration +triangle_wave = np.real(triangle(duration, amp, freq).samples) +plt.plot(range(duration), triangle_wave) +plt.show() +``` + +![../\_images/pulse-2.png](/images/api/qiskit/0.46/pulse-2.png) + +### cos + + + +`qiskit.pulse.library.cos(duration, amp, freq=None, phase=0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates cosine wave [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, $\omega=$ `freq`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = A \cos(2 \pi \omega x + \phi) +$$ + + + The function `qiskit.pulse.library.discrete.cos()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including cos() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Cos(…).get\_waveform(). Note that pulse.Cos() does not support complex values for amp. Instead, use two float values for (amp, angle). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude. +* **freq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse frequency, units of 1/dt. If `None` defaults to single cycle. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse phase. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### sin + + + +`qiskit.pulse.library.sin(duration, amp, freq=None, phase=0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates sine wave [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, $\omega=$ `freq`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = A \sin(2 \pi \omega x + \phi) +$$ + + + The function `qiskit.pulse.library.discrete.sin()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including sin() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Sin(…).get\_waveform(). Note that pulse.Sin() does not support complex values for amp. Instead, use two float values for (amp, angle). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude. +* **freq** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse frequency, units of 1/dt. If `None` defaults to single cycle. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse phase. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### gaussian + + + +`qiskit.pulse.library.gaussian(duration, amp, sigma, name=None, zero_ends=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates unnormalized gaussian [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp` and $\sigma=$ `sigma`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = A\exp\left(\left(\frac{x - \mu}{2\sigma}\right)^2 \right), +$$ + +with the center $\mu=$ `duration/2`. + +If `zero_ends==True`, each output sample $y$ is modified according to: + +$$ +y \mapsto A\frac{y-y^*}{A-y^*}, +$$ + +where $y^*$ is the value of the endpoint samples. This sets the endpoints to $0$ while preserving the amplitude at the center. If $A=y^*$, $y$ is set to $1$. By default, the endpoints are at `x = -1, x = duration + 1`. + +Integrated area under the full curve is `amp * np.sqrt(2*np.pi*sigma**2)` + + + The function `qiskit.pulse.library.discrete.gaussian()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including gaussian() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Gaussian(…).get\_waveform(). Note that complex value support for the amp parameter is deprecated in the SymbolicPulse library. It is therefore recommended to use two float values for (amp, angle) instead of complex amp + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude at `duration/2`. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width (standard deviation) of pulse. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. +* **zero\_ends** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### gaussian\_deriv + + + +`qiskit.pulse.library.gaussian_deriv(duration, amp, sigma, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates unnormalized gaussian derivative [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp` and $\sigma=$ `sigma` applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = -A\frac{(x - \mu)}{\sigma^2}\exp + \left(-\frac{1}{2}\left(\frac{x - \mu}{\sigma}\right)^2 \right) +$$ + +i.e. the derivative of the Gaussian function, with center $\mu=$ `duration/2`. + + + The function `qiskit.pulse.library.discrete.gaussian_deriv()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including gaussian\_deriv() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.GaussianDeriv(…).get\_waveform(). Note that pulse.GaussianDeriv() does not support complex values for amp. Instead, use two float values for (amp, angle). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude of corresponding Gaussian at the pulse center (`duration/2`). +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width (standard deviation) of pulse. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### sech + + + +`qiskit.pulse.library.sech(duration, amp, sigma, name=None, zero_ends=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates unnormalized sech [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp` and $\sigma=$ `sigma`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = A\text{sech}\left(\frac{x-\mu}{\sigma} \right) +$$ + +with the center $\mu=$ `duration/2`. + +If `zero_ends==True`, each output sample $y$ is modified according to: + +$$ +y \mapsto A\frac{y-y^*}{A-y^*}, +$$ + +where $y^*$ is the value of the endpoint samples. This sets the endpoints to $0$ while preserving the amplitude at the center. If $A=y^*$, $y$ is set to $1$. By default, the endpoints are at `x = -1, x = duration + 1`. + + + The function `qiskit.pulse.library.discrete.sech()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including sech() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Sech(…).get\_waveform(). Note that pulse.Sech() does not support complex values for amp. Instead, use two float values for (amp, angle). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude at duration/2. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width (standard deviation) of pulse. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of pulse. +* **zero\_ends** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### sech\_deriv + + + +`qiskit.pulse.library.sech_deriv(duration, amp, sigma, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates unnormalized sech derivative [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $A=$ `amp`, $\sigma=$ `sigma`, and center $\mu=$ `duration/2`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = \frac{d}{dx}\left[A\text{sech}\left(\frac{x-\mu}{\sigma} \right)\right], + + +$$ + +i.e. the derivative of $\text{sech}$. + + + The function `qiskit.pulse.library.discrete.sech_deriv()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including sech\_deriv() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.SechDeriv(…).get\_waveform(). Note that pulse.SechDeriv() does not support complex values for amp. Instead, use two float values for (amp, angle). + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude at center. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width (standard deviation) of pulse. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of pulse. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### gaussian\_square + + + +`qiskit.pulse.library.gaussian_square(duration, amp, sigma, risefall=None, width=None, name=None, zero_ends=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates gaussian square [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). + +For $d=$ `duration`, $A=$ `amp`, $\sigma=$ `sigma`, and $r=$ `risefall`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = \begin{cases} + g(x - r) ) & x\leq r \\ + A & r\leq x\leq d-r \\ + g(x - (d - r)) & d-r\leq x + \end{cases} +$$ + +where $g(x)$ is the Gaussian function sampled from in [`gaussian()`](#qiskit.pulse.library.gaussian "qiskit.pulse.library.gaussian") with $A=$ `amp`, $\mu=1$, and $\sigma=$ `sigma`. I.e. $f(x)$ represents a square pulse with smooth Gaussian edges. + +If `zero_ends == True`, the samples for the Gaussian ramps are remapped as in [`gaussian()`](#qiskit.pulse.library.gaussian "qiskit.pulse.library.gaussian"). + + + The function `qiskit.pulse.library.discrete.gaussian_square()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including gaussian\_square() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.GaussianSquare(…).get\_waveform(). Note that complex value support for the amp parameter is deprecated in the SymbolicPulse library. It is therefore recommended to use two float values for (amp, angle) instead of complex amp + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width (standard deviation) of Gaussian rise/fall portion of the pulse. +* **risefall** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Number of samples over which pulse rise and fall happen. Width of square portion of pulse will be `duration-2*risefall`. +* **width** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The duration of the embedded square pulse. Only one of `width` or `risefall` should be specified as the functional form requires `width = duration - 2 * risefall`. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. +* **zero\_ends** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp. + +**Raises** + +[**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If `risefall` and `width` arguments are inconsistent or not enough info. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### drag + + + +`qiskit.pulse.library.drag(duration, amp, sigma, beta, name=None, zero_ends=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/discrete.py "view source code") + +Generates Y-only correction DRAG [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform") for standard nonlinear oscillator (SNO) \[1]. + +For $A=$ `amp`, $\sigma=$ `sigma`, and $\beta=$ `beta`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function: + +$$ +f(x) = g(x) + i \beta h(x), +$$ + +where $g(x)$ is the function sampled in [`gaussian()`](#qiskit.pulse.library.gaussian "qiskit.pulse.library.gaussian"), and $h(x)$ is the function sampled in [`gaussian_deriv()`](#qiskit.pulse.library.gaussian_deriv "qiskit.pulse.library.gaussian_deriv"). + +If `zero_ends == True`, the samples from $g(x)$ are remapped as in [`gaussian()`](#qiskit.pulse.library.gaussian "qiskit.pulse.library.gaussian"). + + + The function `qiskit.pulse.library.discrete.drag()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. The discrete pulses library, including drag() is deprecated. Instead, use the SymbolicPulse library to create the waveform with pulse.Drag(…).get\_waveform(). Note that complex value support for the amp parameter is deprecated in the SymbolicPulse library. It is therefore recommended to use two float values for (amp, angle) instead of complex amp + + +**References** + +1. [*Gambetta, J. M., Motzoi, F., Merkel, S. T. & Wilhelm, F. K. “Analytic control methods for high-fidelity unitary operations in a weakly nonlinear oscillator.” Phys. Rev. A 83, 012308 (2011).*](http://dx.doi.org/10.1103/PhysRevA.83.012308) + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. Must be greater than zero. +* **amp** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Pulse amplitude at center `duration/2`. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width (standard deviation) of pulse. +* **beta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Y correction amplitude. For the SNO this is $\beta=-\frac{\lambda_1^2}{4\Delta_2}$. Where $\lambda_1$ is the relative coupling strength between the first excited and second excited states and $\Delta_2$ is the detuning between the respective excited states. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse. +* **zero\_ends** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + + + +### Parametric Pulse Representation + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Constant`](qiskit.pulse.library.Constant_class.rst#qiskit.pulse.library.Constant "qiskit.pulse.library.Constant")(duration, amp\[, angle, name, ...]) | A simple constant pulse, with an amplitude value and a duration: | +| [`Drag`](qiskit.pulse.library.Drag_class.rst#qiskit.pulse.library.Drag "qiskit.pulse.library.Drag")(duration, amp, sigma, beta\[, angle, ...]) | The Derivative Removal by Adiabatic Gate (DRAG) pulse is a standard Gaussian pulse with an additional Gaussian derivative component and lifting applied. | +| [`Gaussian`](qiskit.pulse.library.Gaussian_class.rst#qiskit.pulse.library.Gaussian "qiskit.pulse.library.Gaussian")(duration, amp, sigma\[, angle, ...]) | A lifted and truncated pulse envelope shaped according to the Gaussian function whose mean is centered at the center of the pulse (duration / 2): | +| [`GaussianSquare`](qiskit.pulse.library.GaussianSquare "qiskit.pulse.library.GaussianSquare")(duration, amp, sigma\[, ...]) | A square pulse with a Gaussian shaped risefall on both sides lifted such that its first sample is zero. | +| [`GaussianSquareDrag`](qiskit.pulse.library.GaussianSquareDrag "qiskit.pulse.library.GaussianSquareDrag")(duration, amp, sigma, beta) | A square pulse with a Drag shaped rise and fall | +| [`gaussian_square_echo`](qiskit.pulse.library.gaussian_square_echo "qiskit.pulse.library.gaussian_square_echo")(duration, amp, sigma\[, ...]) | An echoed Gaussian square pulse with an active tone overlaid on it. | +| [`GaussianDeriv`](qiskit.pulse.library.GaussianDeriv "qiskit.pulse.library.GaussianDeriv")(duration, amp, sigma\[, angle, ...]) | An unnormalized Gaussian derivative pulse. | +| [`Sin`](qiskit.pulse.library.Sin_class.rst#qiskit.pulse.library.Sin "qiskit.pulse.library.Sin")(duration, amp, phase\[, freq, angle, ...]) | A sinusoidal pulse. | +| [`Cos`](qiskit.pulse.library.Cos_class.rst#qiskit.pulse.library.Cos "qiskit.pulse.library.Cos")(duration, amp, phase\[, freq, angle, ...]) | A cosine pulse. | +| [`Sawtooth`](qiskit.pulse.library.Sawtooth_class.rst#qiskit.pulse.library.Sawtooth "qiskit.pulse.library.Sawtooth")(duration, amp, phase\[, freq, ...]) | A sawtooth pulse. | +| [`Triangle`](qiskit.pulse.library.Triangle_class.rst#qiskit.pulse.library.Triangle "qiskit.pulse.library.Triangle")(duration, amp, phase\[, freq, ...]) | A triangle wave pulse. | +| [`Square`](qiskit.pulse.library.Square_fun.rst#qiskit.pulse.library.Square "qiskit.pulse.library.Square")(duration, amp, phase\[, freq, angle, ...]) | A square wave pulse. | +| [`Sech`](qiskit.pulse.library.Sech_fun.rst#qiskit.pulse.library.Sech "qiskit.pulse.library.Sech")(duration, amp, sigma\[, angle, name, ...]) | An unnormalized sech pulse. | +| [`SechDeriv`](qiskit.pulse.library.SechDeriv "qiskit.pulse.library.SechDeriv")(duration, amp, sigma\[, angle, ...]) | An unnormalized sech derivative pulse. | + + + + + + + +## Channels + + + +`qiskit.pulse.channels` + +Pulse is meant to be agnostic to the underlying hardware implementation, while still allowing low-level control. Therefore, our signal channels are *virtual* hardware channels. The backend which executes our programs is responsible for mapping these virtual channels to the proper physical channel within the quantum control hardware. + +Channels are characterized by their type and their index. Channels include: + +* transmit channels, which should subclass `PulseChannel` +* receive channels, such as [`AcquireChannel`](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") +* non-signal “channels” such as [`SnapshotChannel`](qiskit.pulse.channels.SnapshotChannel "qiskit.pulse.channels.SnapshotChannel"), [`MemorySlot`](qiskit.pulse.channels.MemorySlot "qiskit.pulse.channels.MemorySlot") and `RegisterChannel`. + +Novel channel types can often utilize the [`ControlChannel`](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel"), but if this is not sufficient, new channel types can be created. Then, they must be supported in the PulseQobj schema and the assembler. Channels are characterized by their type and their index. See each channel type below to learn more. + +| | | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [`DriveChannel`](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel")(\*args, \*\*kwargs) | Drive channels transmit signals to qubits which enact gate operations. | +| [`MeasureChannel`](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel")(\*args, \*\*kwargs) | Measure channels transmit measurement stimulus pulses for readout. | +| [`AcquireChannel`](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel")(\*args, \*\*kwargs) | Acquire channels are used to collect data. | +| [`ControlChannel`](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")(\*args, \*\*kwargs) | Control channels provide supplementary control over the qubit to the drive channel. | +| [`RegisterSlot`](qiskit.pulse.channels.RegisterSlot "qiskit.pulse.channels.RegisterSlot")(\*args, \*\*kwargs) | Classical resister slot channels represent classical registers (low-latency classical memory). | +| [`MemorySlot`](qiskit.pulse.channels.MemorySlot "qiskit.pulse.channels.MemorySlot")(\*args, \*\*kwargs) | Memory slot channels represent classical memory storage. | +| [`SnapshotChannel`](qiskit.pulse.channels.SnapshotChannel "qiskit.pulse.channels.SnapshotChannel")(\*args, \*\*kwargs) | Snapshot channels are used to specify instructions for simulators. | + +All channels are children of the same abstract base class: + + + +`qiskit.pulse.channels.Channel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Base class of channels. Channels provide a Qiskit-side label for typical quantum control hardware signal channels. The final label -> physical channel mapping is the responsibility of the hardware backend. For instance, `DriveChannel(0)` holds instructions which the backend should map to the signal line driving gate operations on the qubit labeled (indexed) 0. + +When serialized channels are identified by their serialized name ``. The type of the channel is interpreted from the prefix, and the index often (but not always) maps to the qubit index. All concrete channel classes must have a `prefix` class attribute (and instances of that class have an index attribute). Base classes which have `prefix` set to `None` are prevented from being instantiated. + +To implement a new channel inherit from [`Channel`](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") and provide a unique string identifier for the `prefix` class attribute. + +Channel class. + +**Parameters** + +**index** – Index of channel. + + + +## Schedules + +Schedules are Pulse programs. They describe instruction sequences for the control hardware. The Schedule is one of the most fundamental objects to this pulse-level programming module. A `Schedule` is a representation of a *program* in Pulse. Each schedule tracks the time of each instruction occuring in parallel over multiple signal *channels*. + +| | | +| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule")(\*schedules\[, name, metadata]) | A quantum program *schedule* with exact time constraints for its instructions, operating over all input signal *channels* and supporting special syntaxes for building. | +| [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")(\[name, metadata, ...]) | Time-ordered sequence of instructions with alignment context. | + + + + + +## Pulse Transforms + + + +`qiskit.pulse.transforms` + +The pulse transforms provide transformation routines to reallocate and optimize pulse programs for backends. + + + +### Alignments + +The alignment transforms define alignment policies of instructions in [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"). These transformations are called to create [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule")s from [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")s. + +| | | +| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| [`AlignEquispaced`](qiskit.pulse.transforms.AlignEquispaced "qiskit.pulse.transforms.AlignEquispaced")(duration) | Align instructions with equispaced interval within a specified duration. | +| [`AlignFunc`](qiskit.pulse.transforms.AlignFunc "qiskit.pulse.transforms.AlignFunc")(duration, func) | Allocate instructions at position specified by callback function. | +| [`AlignLeft`](qiskit.pulse.transforms.AlignLeft "qiskit.pulse.transforms.AlignLeft")() | Align instructions in as-soon-as-possible manner. | +| [`AlignRight`](qiskit.pulse.transforms.AlignRight "qiskit.pulse.transforms.AlignRight")() | Align instructions in as-late-as-possible manner. | +| [`AlignSequential`](qiskit.pulse.transforms.AlignSequential "qiskit.pulse.transforms.AlignSequential")() | Align instructions sequentially. | + +These are all subtypes of the abstract base class [`AlignmentKind`](#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.AlignmentKind"). + + + +`qiskit.pulse.transforms.AlignmentKind(context_params)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/alignments.py "view source code") + +An abstract class for schedule alignment. + +Create new context. + + + +### Canonicalization + +The canonicalization transforms convert schedules to a form amenable for execution on OpenPulse backends. + +### add\_implicit\_acquires + + + +`qiskit.pulse.transforms.add_implicit_acquires(schedule, meas_map)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Return a new schedule with implicit acquires from the measurement mapping replaced by explicit ones. + + + Since new acquires are being added, Memory Slots will be set to match the qubit index. This may overwrite your specification. + + +**Parameters** + +* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule to be aligned. +* **meas\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – List of lists of qubits that are measured together. + +**Returns** + +A `Schedule` with the additional acquisition instructions. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### align\_measures + + + +`qiskit.pulse.transforms.align_measures(schedules, inst_map=None, cal_gate='u3', max_calibration_duration=None, align_time=None, align_all=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Return new schedules where measurements occur at the same physical time. + +This transformation will align the first [`Acquire`](qiskit.pulse.instructions.Acquire "qiskit.pulse.instructions.Acquire") on every channel to occur at the same time. + +Minimum measurement wait time (to allow for calibration pulses) is enforced and may be set with `max_calibration_duration`. + +By default only instructions containing a [`AcquireChannel`](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") or [`MeasureChannel`](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") will be shifted. If you wish to keep the relative timing of all instructions in the schedule set `align_all=True`. + +This method assumes that `MeasureChannel(i)` and `AcquireChannel(i)` correspond to the same qubit and the acquire/play instructions should be shifted together on these channels. + +```python +from qiskit import pulse +from qiskit.pulse import transforms + +d0 = pulse.DriveChannel(0) +m0 = pulse.MeasureChannel(0) +a0 = pulse.AcquireChannel(0) +mem0 = pulse.MemorySlot(0) + +sched = pulse.Schedule() +sched.append(pulse.Play(pulse.Constant(10, 0.5), d0), inplace=True) +sched.append(pulse.Play(pulse.Constant(10, 1.), m0).shift(sched.duration), inplace=True) +sched.append(pulse.Acquire(20, a0, mem0).shift(sched.duration), inplace=True) + +sched_shifted = sched << 20 + +aligned_sched, aligned_sched_shifted = transforms.align_measures([sched, sched_shifted]) + +assert aligned_sched == aligned_sched_shifted +``` + +If it is desired to only shift acquisition and measurement stimulus instructions set the flag `align_all=False`: + +```python +aligned_sched, aligned_sched_shifted = transforms.align_measures( + [sched, sched_shifted], + align_all=False, +) + +assert aligned_sched != aligned_sched_shifted +``` + +**Parameters** + +* **schedules** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")*]*) – Collection of schedules to be aligned together +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.instruction_schedule_map.InstructionScheduleMap") *| None*) – Mapping of circuit operations to pulse schedules +* **cal\_gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the gate to inspect for the calibration time +* **max\_calibration\_duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – If provided, inst\_map and cal\_gate will be ignored +* **align\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – If provided, this will be used as final align time. +* **align\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Shift all instructions in the schedule such that they maintain their relative alignment with the shifted acquisition instruction. If `False` only the acquisition and measurement pulse instructions will be shifted. + +**Returns** + +The input list of schedules transformed to have their measurements aligned. + +**Raises** + +[**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the provided alignment time is negative. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")] + +### block\_to\_schedule + + + +`qiskit.pulse.transforms.block_to_schedule(block)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Convert `ScheduleBlock` to `Schedule`. + +**Parameters** + +**block** ([*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")) – A `ScheduleBlock` to convert. + +**Returns** + +Scheduled pulse program. + +**Raises** + +* [**UnassignedDurationError**](#qiskit.pulse.UnassignedDurationError "qiskit.pulse.UnassignedDurationError") – When any instruction duration is not assigned. +* [**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When the alignment context duration is shorter than the schedule duration. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + + + This transform may insert barriers in between contexts. + + +### compress\_pulses + + + +`qiskit.pulse.transforms.compress_pulses(schedules)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Optimization pass to replace identical pulses. + +**Parameters** + +**schedules** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")*]*) – Schedules to compress. + +**Returns** + +Compressed schedules. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")] + +### flatten + + + +`qiskit.pulse.transforms.flatten(program)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Flatten (inline) any called nodes into a Schedule tree with no nested children. + +**Parameters** + +**program** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Pulse program to remove nested structure. + +**Returns** + +Flatten pulse program. + +**Raises** + +[**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When invalid data format is given. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### inline\_subroutines + + + +`qiskit.pulse.transforms.inline_subroutines(program)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Recursively remove call instructions and inline the respective subroutine instructions. + +Assigned parameter values, which are stored in the parameter table, are also applied. The subroutine is copied before the parameter assignment to avoid mutation problem. + +**Parameters** + +**program** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")) – A program which may contain the subroutine, i.e. `Call` instruction. + +**Returns** + +A schedule without subroutine. + +**Raises** + +[**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When input program is not valid data format. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### pad + + + +`qiskit.pulse.transforms.pad(schedule, channels=None, until=None, inplace=False, pad_with=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Pad the input Schedule with `Delay``s on all unoccupied timeslots until ``schedule.duration` or `until` if not `None`. + +**Parameters** + +* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Schedule to pad. +* **channels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Channel*](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – Channels to pad. Defaults to all channels in `schedule` if not provided. If the supplied channel is not a member of `schedule` it will be added. +* **until** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Time to pad until. Defaults to `schedule.duration` if not provided. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Pad this schedule by mutating rather than returning a new schedule. +* **pad\_with** ([*Type*](https://docs.python.org/3/library/typing.html#typing.Type "(in Python v3.12)")*\[*[*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")*] | None*) – Pulse `Instruction` subclass to be used for padding. Default to [`Delay`](qiskit.pulse.instructions.Delay "qiskit.pulse.instructions.Delay") instruction. + +**Returns** + +The padded schedule. + +**Raises** + +[**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When non pulse instruction is set to pad\_with. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### remove\_directives + + + +`qiskit.pulse.transforms.remove_directives(schedule)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Remove directives. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – A schedule to remove compiler directives. + +**Returns** + +A schedule without directives. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### remove\_trivial\_barriers + + + +`qiskit.pulse.transforms.remove_trivial_barriers(schedule)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/canonicalization.py "view source code") + +Remove trivial barriers with 0 or 1 channels. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – A schedule to remove trivial barriers. + +**Returns** + +A schedule without trivial barriers + +**Return type** + +schedule + + + +### DAG + +The DAG transforms create DAG representation of input program. This can be used for optimization of instructions and equality checks. + +### block\_to\_dag + + + +`qiskit.pulse.transforms.block_to_dag(block)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/dag.py "view source code") + +Convert schedule block instruction into DAG. + +`ScheduleBlock` can be represented as a DAG as needed. For example, equality of two programs are efficiently checked on DAG representation. + +```python +with pulse.build() as sched1: + with pulse.align_left(): + pulse.play(my_gaussian0, pulse.DriveChannel(0)) + pulse.shift_phase(1.57, pulse.DriveChannel(2)) + pulse.play(my_gaussian1, pulse.DriveChannel(1)) + +with pulse.build() as sched2: + with pulse.align_left(): + pulse.shift_phase(1.57, pulse.DriveChannel(2)) + pulse.play(my_gaussian1, pulse.DriveChannel(1)) + pulse.play(my_gaussian0, pulse.DriveChannel(0)) +``` + +Here the `sched1 `` and ``sched2` are different implementations of the same program, but it is difficult to confirm on the list representation. + +Another example is instruction optimization. + +```python +with pulse.build() as sched: + with pulse.align_left(): + pulse.shift_phase(1.57, pulse.DriveChannel(1)) + pulse.play(my_gaussian0, pulse.DriveChannel(0)) + pulse.shift_phase(-1.57, pulse.DriveChannel(1)) +``` + +In above program two `shift_phase` instructions can be cancelled out because they are consecutive on the same drive channel. This can be easily found on the DAG representation. + +**Parameters** + +**block** (*"ScheduleBlock"*) – A schedule block to be converted. + +**Returns** + +Instructions in DAG representation. + +**Raises** + +[**PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When the context is invalid subclass. + +**Return type** + +[*PyDAG*](https://www.rustworkx.org/apiref/rustworkx.PyDAG.html#rustworkx.PyDAG "(in rustworkx v0.14.0)") + + + +### Composite transform + +A sequence of transformations to generate a target code. + +### target\_qobj\_transform + + + +`qiskit.pulse.transforms.target_qobj_transform(sched, remove_directives=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/base_transforms.py "view source code") + +A basic pulse program transformation for OpenPulse API execution. + +**Parameters** + +* **sched** ([*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")*] |* [*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")*] |* [*Instruction*](#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")*]*) – Input program to transform. +* **remove\_directives** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to remove compiler directives. + +**Returns** + +Transformed program for execution. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + + + + + +## Pulse Builder + +Use the pulse builder DSL to write pulse programs with an imperative syntax. + + + The pulse builder interface is still in active development. It may have breaking API changes without deprecation warnings in future releases until otherwise indicated. + + +The pulse builder provides an imperative API for writing pulse programs with less difficulty than the [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") API. It contextually constructs a pulse schedule and then emits the schedule for execution. For example, to play a series of pulses on channels is as simple as: + +```python +from qiskit import pulse + +dc = pulse.DriveChannel +d0, d1, d2, d3, d4 = dc(0), dc(1), dc(2), dc(3), dc(4) + +with pulse.build(name='pulse_programming_in') as pulse_prog: + pulse.play([1, 1, 1, 0, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 0, 1, 1, 1], d0) + pulse.play([1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0], d1) + pulse.play([1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0], d2) + pulse.play([1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0], d3) + pulse.play([1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 0], d4) + +pulse_prog.draw() +``` + +![../\_images/pulse-3.png](/images/api/qiskit/0.46/pulse-3.png) + +To begin pulse programming we must first initialize our program builder context with [`build()`](#qiskit.pulse.builder.build "qiskit.pulse.builder.build"), after which we can begin adding program statements. For example, below we write a simple program that [`play()`](#qiskit.pulse.builder.play "qiskit.pulse.builder.play")s a pulse: + +```python +from qiskit import execute, pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.play(pulse.Constant(100, 1.0), d0) + +pulse_prog.draw() +``` + +![../\_images/pulse-4.png](/images/api/qiskit/0.46/pulse-4.png) + +The builder initializes a [`pulse.Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"), `pulse_prog` and then begins to construct the program within the context. The output pulse schedule will survive after the context is exited and can be executed like a normal Qiskit schedule using `qiskit.execute(pulse_prog, backend)`. + +Pulse programming has a simple imperative style. This leaves the programmer to worry about the raw experimental physics of pulse programming and not constructing cumbersome data structures. + +We can optionally pass a [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") to [`build()`](#qiskit.pulse.builder.build "qiskit.pulse.builder.build") to enable enhanced functionality. Below, we prepare a Bell state by automatically compiling the required pulses from their gate-level representations, while simultaneously applying a long decoupling pulse to a neighboring qubit. We terminate the experiment with a measurement to observe the state we prepared. This program which mixes circuits and pulses will be automatically lowered to be run as a pulse program: + +```python +import math + +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse3Q + +# TODO: This example should use a real mock backend. +backend = FakeOpenPulse3Q() + +d2 = pulse.DriveChannel(2) + +with pulse.build(backend) as bell_prep: + pulse.u2(0, math.pi, 0) + pulse.cx(0, 1) + +with pulse.build(backend) as decoupled_bell_prep_and_measure: + # We call our bell state preparation schedule constructed above. + with pulse.align_right(): + pulse.call(bell_prep) + pulse.play(pulse.Constant(bell_prep.duration, 0.02), d2) + pulse.barrier(0, 1, 2) + registers = pulse.measure_all() + +decoupled_bell_prep_and_measure.draw() +``` + +![../\_images/pulse-5.png](/images/api/qiskit/0.46/pulse-5.png) + + + Calling gates directly within the pulse builder namespace is deprecated as of qiskit 0.46.0. + + +With the pulse builder we are able to blend programming on qubits and channels. While the pulse schedule is based on instructions that operate on channels, the pulse builder automatically handles the mapping from qubits to channels for you. + +In the example below we demonstrate some more features of the pulse builder: + +```python +import math + +from qiskit import pulse, QuantumCircuit +from qiskit.pulse import library +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend) as pulse_prog: + # Create a pulse. + gaussian_pulse = library.gaussian(10, 1.0, 2) + # Get the qubit's corresponding drive channel from the backend. + d0 = pulse.drive_channel(0) + d1 = pulse.drive_channel(1) + # Play a pulse at t=0. + pulse.play(gaussian_pulse, d0) + # Play another pulse directly after the previous pulse at t=10. + pulse.play(gaussian_pulse, d0) + # The default scheduling behavior is to schedule pulses in parallel + # across channels. For example, the statement below + # plays the same pulse on a different channel at t=0. + pulse.play(gaussian_pulse, d1) + + # We also provide pulse scheduling alignment contexts. + # The default alignment context is align_left. + + # The sequential context schedules pulse instructions sequentially in time. + # This context starts at t=10 due to earlier pulses above. + with pulse.align_sequential(): + pulse.play(gaussian_pulse, d0) + # Play another pulse after at t=20. + pulse.play(gaussian_pulse, d1) + + # We can also nest contexts as each instruction is + # contained in its local scheduling context. + # The output of a child context is a context-schedule + # with the internal instructions timing fixed relative to + # one another. This is schedule is then called in the parent context. + + # Context starts at t=30. + with pulse.align_left(): + # Start at t=30. + pulse.play(gaussian_pulse, d0) + # Start at t=30. + pulse.play(gaussian_pulse, d1) + # Context ends at t=40. + + # Alignment context where all pulse instructions are + # aligned to the right, ie., as late as possible. + with pulse.align_right(): + # Shift the phase of a pulse channel. + pulse.shift_phase(math.pi, d1) + # Starts at t=40. + pulse.delay(100, d0) + # Ends at t=140. + + # Starts at t=130. + pulse.play(gaussian_pulse, d1) + # Ends at t=140. + + # Acquire data for a qubit and store in a memory slot. + pulse.acquire(100, 0, pulse.MemorySlot(0)) + + # We also support a variety of macros for common operations. + + # Measure all qubits. + pulse.measure_all() + + # Delay on some qubits. + # This requires knowledge of which channels belong to which qubits. + # delay for 100 cycles on qubits 0 and 1. + pulse.delay_qubits(100, 0, 1) + + # Call a quantum circuit. The pulse builder lazily constructs a quantum + # circuit which is then transpiled and scheduled before inserting into + # a pulse schedule. + # NOTE: Quantum register indices correspond to physical qubit indices. + qc = QuantumCircuit(2, 2) + qc.cx(0, 1) + pulse.call(qc) + # Calling a small set of standard gates and decomposing to pulses is + # also supported with more natural syntax. + pulse.u3(0, math.pi, 0, 0) + pulse.cx(0, 1) + + + # It is also be possible to call a preexisting schedule + tmp_sched = pulse.Schedule() + tmp_sched += pulse.Play(gaussian_pulse, d0) + pulse.call(tmp_sched) + + # We also support: + + # frequency instructions + pulse.set_frequency(5.0e9, d0) + + # phase instructions + pulse.shift_phase(0.1, d0) + + # offset contexts + with pulse.phase_offset(math.pi, d0): + pulse.play(gaussian_pulse, d0) +``` + + + Calling gates directly within the pulse builder namespace is deprecated as of qiskit 0.46.0. + + +The above is just a small taste of what is possible with the builder. See the rest of the module documentation for more information on its capabilities. + +### build + + + +`qiskit.pulse.builder.build(backend=None, schedule=None, name=None, default_alignment='left', default_transpiler_settings=None, default_circuit_scheduler_settings=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Create a context manager for launching the imperative pulse builder DSL. + +To enter a building context and starting building a pulse program: + +```python +from qiskit import transpile, pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.play(pulse.Constant(100, 0.5), d0) +``` + +While the output program `pulse_prog` cannot be executed as we are using a mock backend. If a real backend is being used, executing the program is done with: + +```python +backend.run(transpile(pulse_prog, backend)) +``` + + + `qiskit.pulse.builder.build()`’s argument `default_circuit_scheduler_settings` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. setting parameter `default_circuit_scheduler_settings` in build() was used for gate operations, which are deprecated. pulse schedules should only be used for gate calibrations as part of a quantum circuit, and not vice versa + + + + `qiskit.pulse.builder.build()`’s argument `default_transpiler_settings` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. setting parameter `default_transpiler_settings` in build() was used for gate operations, which are deprecated. pulse schedules should only be used for gate calibrations as part of a quantum circuit, and not vice versa + + +**Parameters** + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – A Qiskit backend. If not supplied certain builder functionality will be unavailable. +* **schedule** ([*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *| None*) – A pulse `ScheduleBlock` in which your pulse program will be built. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of pulse program to be built. +* **default\_alignment** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*AlignmentKind*](#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") *| None*) – Default scheduling alignment for builder. One of `left`, `right`, `sequential` or an alignment context. +* **default\_transpiler\_settings** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Default settings for the transpiler. +* **default\_circuit\_scheduler\_settings** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Default settings for the circuit to pulse scheduler. + +**Returns** + +A new builder context which has the active builder initialized. + +**Return type** + +[*ContextManager*](https://docs.python.org/3/library/typing.html#typing.ContextManager "(in Python v3.12)")\[[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")] + +### Channels + +Methods to return the correct channels for the respective qubit indices. + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeArmonk + +backend = FakeArmonk() + +with pulse.build(backend) as drive_sched: + d0 = pulse.drive_channel(0) + print(d0) +``` + +```python +DriveChannel(0) +``` + +### acquire\_channel + + + +`qiskit.pulse.builder.acquire_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return `AcquireChannel` for `qubit` on the active builder backend. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + assert pulse.acquire_channel(0) == pulse.AcquireChannel(0) +``` + + + Requires the active builder context to have a backend set. + + +**Return type** + +[*AcquireChannel*](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channels + + + +`qiskit.pulse.builder.control_channels(*qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return `ControlChannel` for `qubit` on the active builder backend. + +Return the secondary drive channel for the given qubit – typically utilized for controlling multi-qubit interactions. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() +with pulse.build(backend): + assert pulse.control_channels(0, 1) == [pulse.ControlChannel(0)] +``` + + + Requires the active builder context to have a backend set. + + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of ordered qubits of the form (control\_qubit, target\_qubit). + +**Returns** + +List of control channels associated with the supplied ordered list of qubits. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*ControlChannel*](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`qiskit.pulse.builder.drive_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return `DriveChannel` for `qubit` on the active builder backend. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + assert pulse.drive_channel(0) == pulse.DriveChannel(0) +``` + + + Requires the active builder context to have a backend set. + + +**Return type** + +[*DriveChannel*](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`qiskit.pulse.builder.measure_channel(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return `MeasureChannel` for `qubit` on the active builder backend. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + assert pulse.measure_channel(0) == pulse.MeasureChannel(0) +``` + + + Requires the active builder context to have a backend set. + + +**Return type** + +[*MeasureChannel*](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### Instructions + +Pulse instructions are available within the builder interface. Here’s an example: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeArmonk + +backend = FakeArmonk() + +with pulse.build(backend) as drive_sched: + d0 = pulse.drive_channel(0) + a0 = pulse.acquire_channel(0) + + pulse.play(pulse.library.Constant(10, 1.0), d0) + pulse.delay(20, d0) + pulse.shift_phase(3.14/2, d0) + pulse.set_phase(3.14, d0) + pulse.shift_frequency(1e7, d0) + pulse.set_frequency(5e9, d0) + + with pulse.build() as temp_sched: + pulse.play(pulse.library.Gaussian(20, 1.0, 3.0), d0) + pulse.play(pulse.library.Gaussian(20, -1.0, 3.0), d0) + + pulse.call(temp_sched) + pulse.acquire(30, a0, pulse.MemorySlot(0)) + +drive_sched.draw() +``` + +![../\_images/pulse-6.png](/images/api/qiskit/0.46/pulse-6.png) + +### acquire + + + +`qiskit.pulse.builder.acquire(duration, qubit_or_channel, register, **metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Acquire for a `duration` on a `channel` and store the result in a `register`. + +Examples: + +```python +from qiskit import pulse + +acq0 = pulse.AcquireChannel(0) +mem0 = pulse.MemorySlot(0) + +with pulse.build() as pulse_prog: + pulse.acquire(100, acq0, mem0) + + # measurement metadata + kernel = pulse.configuration.Kernel('linear_discriminator') + pulse.acquire(100, acq0, mem0, kernel=kernel) +``` + + + The type of data acquire will depend on the execution `meas_level`. + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration to acquire data for +* **qubit\_or\_channel** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*AcquireChannel*](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel")) – Either the qubit to acquire data for or the specific [`AcquireChannel`](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") to acquire on. +* **register** (*StorageLocation*) – Location to store measured result. +* **metadata** (*Kernel | Discriminator*) – Additional metadata for measurement. See [`Acquire`](qiskit.pulse.instructions.Acquire "qiskit.pulse.instructions.Acquire") for more information. + +**Raises** + +[**exceptions.PulseError**](#qiskit.pulse.PulseError "qiskit.pulse.exceptions.PulseError") – If the register type is not supported. + +### barrier + + + +`qiskit.pulse.builder.barrier(*channels_or_qubits, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Barrier directive for a set of channels and qubits. + +This directive prevents the compiler from moving instructions across the barrier. Consider the case where we want to enforce that one pulse happens after another on separate channels, this can be done with: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +d0 = pulse.DriveChannel(0) +d1 = pulse.DriveChannel(1) + +with pulse.build(backend) as barrier_pulse_prog: + pulse.play(pulse.Constant(10, 1.0), d0) + pulse.barrier(d0, d1) + pulse.play(pulse.Constant(10, 1.0), d1) +``` + +Of course this could have been accomplished with: + +```python +from qiskit.pulse import transforms + +with pulse.build(backend) as aligned_pulse_prog: + with pulse.align_sequential(): + pulse.play(pulse.Constant(10, 1.0), d0) + pulse.play(pulse.Constant(10, 1.0), d1) + +barrier_pulse_prog = transforms.target_qobj_transform(barrier_pulse_prog) +aligned_pulse_prog = transforms.target_qobj_transform(aligned_pulse_prog) + +assert barrier_pulse_prog == aligned_pulse_prog +``` + +The barrier allows the pulse compiler to take care of more advanced scheduling alignment operations across channels. For example in the case where we are calling an outside circuit or schedule and want to align a pulse at the end of one call: + +```python +import math + +d0 = pulse.DriveChannel(0) + +with pulse.build(backend) as pulse_prog: + with pulse.align_right(): + pulse.x(1) + # Barrier qubit 1 and d0. + pulse.barrier(1, d0) + # Due to barrier this will play before the gate on qubit 1. + pulse.play(pulse.Constant(10, 1.0), d0) + # This will end at the same time as the pulse above due to + # the barrier. + pulse.x(1) +``` + + + Requires the active builder context to have a backend set if qubits are barriered on. + + +**Parameters** + +* **channels\_or\_qubits** ([*Channel*](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Channels or qubits to barrier. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name for the barrier + +### call + + + +`qiskit.pulse.builder.call(target, name=None, value_dict=None, **kw_params)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Call the subroutine within the currently active builder context with arbitrary parameters which will be assigned to the target program. + + + If the `target` program is a [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), then a [`Reference`](qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference") instruction will be created and appended to the current context. The `target` program will be immediately assigned to the current scope as a subroutine. If the `target` program is [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"), it will be wrapped by the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction and appended to the current context to avoid a mixed representation of [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") and [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"). If the `target` program is a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") it will be scheduled and the new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") will be added as a [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction. + + + + QuantumCircuit type for the argument target is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. ScheduleBlock should only be used for gate calibrations in a quantum circuit. Thus, the called quantum circuit should be added to the main circuit instead of to the ScheduleBlock. + + +**Examples** + +1. Calling a schedule block (recommended) + +```python +from qiskit import circuit, pulse +from qiskit.providers.fake_provider import FakeBogotaV2 + +backend = FakeBogotaV2() + +with pulse.build() as x_sched: + pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0)) + +with pulse.build() as pulse_prog: + pulse.call(x_sched) + +print(pulse_prog) +``` + +```python +ScheduleBlock( + ScheduleBlock( + Play( + Gaussian(duration=160, amp=(0.1+0j), sigma=40), + DriveChannel(0) + ), + name="block0", + transform=AlignLeft() + ), + name="block1", + transform=AlignLeft() +) +``` + +The actual program is stored in the reference table attached to the schedule. + +```python +print(pulse_prog.references) +``` + +```python +ReferenceManager: + - ('block0', '634b3b50bd684e26a673af1fbd2d6c81'): ScheduleBlock(Play(Gaussian(... +``` + +In addition, you can call a parameterized target program with parameter assignment. + +```python +amp = circuit.Parameter("amp") + +with pulse.build() as subroutine: + pulse.play(pulse.Gaussian(160, amp, 40), pulse.DriveChannel(0)) + +with pulse.build() as pulse_prog: + pulse.call(subroutine, amp=0.1) + pulse.call(subroutine, amp=0.3) + +print(pulse_prog) +``` + +```python +ScheduleBlock( + ScheduleBlock( + Play( + Gaussian(duration=160, amp=(0.1+0j), sigma=40), + DriveChannel(0) + ), + name="block2", + transform=AlignLeft() + ), + ScheduleBlock( + Play( + Gaussian(duration=160, amp=(0.3+0j), sigma=40), + DriveChannel(0) + ), + name="block2", + transform=AlignLeft() + ), + name="block3", + transform=AlignLeft() +) +``` + +If there is a name collision between parameters, you can distinguish them by specifying each parameter object in a python dictionary. For example, + +```python +amp1 = circuit.Parameter('amp') +amp2 = circuit.Parameter('amp') + +with pulse.build() as subroutine: + pulse.play(pulse.Gaussian(160, amp1, 40), pulse.DriveChannel(0)) + pulse.play(pulse.Gaussian(160, amp2, 40), pulse.DriveChannel(1)) + +with pulse.build() as pulse_prog: + pulse.call(subroutine, value_dict={amp1: 0.1, amp2: 0.3}) + +print(pulse_prog) +``` + +```python +ScheduleBlock( + ScheduleBlock( + Play(Gaussian(duration=160, amp=(0.1+0j), sigma=40), DriveChannel(0)), + Play(Gaussian(duration=160, amp=(0.3+0j), sigma=40), DriveChannel(1)), + name="block4", + transform=AlignLeft() + ), + name="block5", + transform=AlignLeft() +) +``` + +2. Calling a schedule + +```python +x_sched = backend.instruction_schedule_map.get("x", (0,)) + +with pulse.build(backend) as pulse_prog: + pulse.call(x_sched) + +print(pulse_prog) +``` + +```python +ScheduleBlock( + Call( + Schedule( + ( + 0, + Play( + Drag( + duration=160, + amp=(0.18989731546729305+0j), + sigma=40, + beta=-1.201258305015517, + name='drag_86a8' + ), + DriveChannel(0), + name='drag_86a8' + ) + ), + name="x" + ), + name='x' + ), + name="block6", + transform=AlignLeft() +) +``` + +Currently, the backend calibrated gates are provided in the form of [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"). The parameter assignment mechanism is available also for schedules. However, the called schedule is not treated as a reference. + + + Calling a circuit from a schedule is deprecated as of qiskit 0.46.0. The Qiskit execution model has migrating toward the pulse gate model, where schedules are attached to circuits through the [`QuantumCircuit.add_calibration()`](qiskit.circuit.QuantumCircuit#add_calibration "qiskit.circuit.QuantumCircuit.add_calibration") method. Thus, instead of calling a circuit into the schedule, it should instead be added to the main circuit. + + +**Parameters** + +* **target** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *| None*) – Target circuit or pulse schedule to call. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Optional. A unique name of subroutine if defined. When the name is explicitly provided, one cannot call different schedule blocks with the same name. +* **value\_dict** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Optional. Parameters assigned to the `target` program. If this dictionary is provided, the `target` program is copied and then stored in the main built schedule and its parameters are assigned to the given values. This dictionary is keyed on [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects, allowing parameter name collision to be avoided. +* **kw\_params** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Alternative way to provide parameters. Since this is keyed on the string parameter name, the parameters having the same name are all updated together. If you want to avoid name collision, use `value_dict` with [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects instead. + +### delay + + + +`qiskit.pulse.builder.delay(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Delay on a `channel` for a `duration`. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.delay(10, d0) +``` + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of cycles to delay for on `channel`. +* **channel** ([*Channel*](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channel to delay on. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction. + +### play + + + +`qiskit.pulse.builder.play(pulse, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Play a `pulse` on a `channel`. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.play(pulse.Constant(10, 1.0), d0) +``` + +**Parameters** + +* **pulse** (*Pulse |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Pulse to play. +* **channel** (*PulseChannel*) – Channel to play pulse on. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the pulse. + +### reference + + + +`qiskit.pulse.builder.reference(name, *extra_keys)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Refer to undefined subroutine by string keys. + +A [`Reference`](qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference") instruction is implicitly created and a schedule can be separately registered to the reference at a later stage. + +```python +from qiskit import pulse + +with pulse.build() as main_prog: + pulse.reference("x_gate", "q0") + +with pulse.build() as subroutine: + pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0)) + +main_prog.assign_references(subroutine_dict={("x_gate", "q0"): subroutine}) +``` + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of subroutine. +* **extra\_keys** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Helper keys to uniquely specify the subroutine. + +### set\_frequency + + + +`qiskit.pulse.builder.set_frequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Set the `frequency` of a pulse `channel`. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.set_frequency(1e9, d0) +``` + +**Parameters** + +* **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Frequency in Hz to set channel to. +* **channel** (*PulseChannel*) – Channel to set frequency of. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction. + +### set\_phase + + + +`qiskit.pulse.builder.set_phase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Set the `phase` of a pulse `channel`. + +Examples: + +```python +import math + +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.set_phase(math.pi, d0) +``` + +**Parameters** + +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Phase in radians to set channel carrier signal to. +* **channel** (*PulseChannel*) – Channel to set phase of. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction. + +### shift\_frequency + + + +`qiskit.pulse.builder.shift_frequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Shift the `frequency` of a pulse `channel`. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.shift_frequency(1e9, d0) +``` + +**Parameters** + +* **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Frequency in Hz to shift channel frequency by. +* **channel** (*PulseChannel*) – Channel to shift frequency of. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction. + +### shift\_phase + + + +`qiskit.pulse.builder.shift_phase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Shift the `phase` of a pulse `channel`. + +Examples: + +```python +import math + +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + pulse.shift_phase(math.pi, d0) +``` + +**Parameters** + +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Phase in radians to shift channel carrier signal by. +* **channel** (*PulseChannel*) – Channel to shift phase of. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction. + +### snapshot + + + +`qiskit.pulse.builder.snapshot(label, snapshot_type='statevector')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Simulator snapshot. + +Examples: + +```python +from qiskit import pulse + +with pulse.build() as pulse_prog: + pulse.snapshot('first', 'statevector') +``` + +**Parameters** + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Label for snapshot. +* **snapshot\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Type of snapshot. + +### Contexts + +Builder aware contexts that modify the construction of a pulse program. For example an alignment context like [`align_right()`](#qiskit.pulse.builder.align_right "qiskit.pulse.builder.align_right") may be used to align all pulses as late as possible in a pulse program. + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) +d1 = pulse.DriveChannel(1) + +with pulse.build() as pulse_prog: + with pulse.align_right(): + # this pulse will start at t=0 + pulse.play(pulse.Constant(100, 1.0), d0) + # this pulse will start at t=80 + pulse.play(pulse.Constant(20, 1.0), d1) + +pulse_prog.draw() +``` + +![../\_images/pulse-7.png](/images/api/qiskit/0.46/pulse-7.png) + +### align\_equispaced + + + +`qiskit.pulse.builder.align_equispaced(duration)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Equispaced alignment pulse scheduling context. + +Pulse instructions within this context are scheduled with the same interval spacing such that the total length of the context block is `duration`. If the total free `duration` cannot be evenly divided by the number of instructions within the context, the modulo is split and then prepended and appended to the returned schedule. Delay instructions are automatically inserted in between pulses. + +This context is convenient to write a schedule for periodical dynamic decoupling or the Hahn echo sequence. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) +x90 = pulse.Gaussian(10, 0.1, 3) +x180 = pulse.Gaussian(10, 0.2, 3) + +with pulse.build() as hahn_echo: + with pulse.align_equispaced(duration=100): + pulse.play(x90, d0) + pulse.play(x180, d0) + pulse.play(x90, d0) + +hahn_echo.draw() +``` + +![../\_images/pulse-8.png](/images/api/qiskit/0.46/pulse-8.png) + +**Parameters** + +**duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Duration of this context. This should be larger than the schedule duration. + +**Yields** + +None + +**Return type** + +[*AlignmentKind*](#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +**Notes** + +The scheduling is performed for sub-schedules within the context rather than channel-wise. If you want to apply the equispaced context for each channel, you should use the context independently for channels. + +### align\_func + + + +`qiskit.pulse.builder.align_func(duration, func)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Callback defined alignment pulse scheduling context. + +Pulse instructions within this context are scheduled at the location specified by arbitrary callback function position that takes integer index and returns the associated fractional location within \[0, 1]. Delay instruction is automatically inserted in between pulses. + +This context may be convenient to write a schedule of arbitrary dynamical decoupling sequences such as Uhrig dynamical decoupling. + +Examples: + +```python +import numpy as np +from qiskit import pulse + +d0 = pulse.DriveChannel(0) +x90 = pulse.Gaussian(10, 0.1, 3) +x180 = pulse.Gaussian(10, 0.2, 3) + +def udd10_pos(j): + return np.sin(np.pi*j/(2*10 + 2))**2 + +with pulse.build() as udd_sched: + pulse.play(x90, d0) + with pulse.align_func(duration=300, func=udd10_pos): + for _ in range(10): + pulse.play(x180, d0) + pulse.play(x90, d0) + +udd_sched.draw() +``` + +![../\_images/pulse-9.png](/images/api/qiskit/0.46/pulse-9.png) + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Duration of context. This should be larger than the schedule duration. +* **func** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – A function that takes an index of sub-schedule and returns the fractional coordinate of of that sub-schedule. The returned value should be defined within \[0, 1]. The pulse index starts from 1. + +**Yields** + +None + +**Return type** + +[*AlignmentKind*](#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +**Notes** + +The scheduling is performed for sub-schedules within the context rather than channel-wise. If you want to apply the numerical context for each channel, you need to apply the context independently to channels. + +### align\_left + + + +`qiskit.pulse.builder.align_left()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Left alignment pulse scheduling context. + +Pulse instructions within this context are scheduled as early as possible by shifting them left to the earliest available time. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) +d1 = pulse.DriveChannel(1) + +with pulse.build() as pulse_prog: + with pulse.align_left(): + # this pulse will start at t=0 + pulse.play(pulse.Constant(100, 1.0), d0) + # this pulse will start at t=0 + pulse.play(pulse.Constant(20, 1.0), d1) +pulse_prog = pulse.transforms.block_to_schedule(pulse_prog) + +assert pulse_prog.ch_start_time(d0) == pulse_prog.ch_start_time(d1) +``` + +**Yields** + +None + +**Return type** + +[*ContextManager*](https://docs.python.org/3/library/typing.html#typing.ContextManager "(in Python v3.12)")\[None] + +### align\_right + + + +`qiskit.pulse.builder.align_right()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Right alignment pulse scheduling context. + +Pulse instructions within this context are scheduled as late as possible by shifting them right to the latest available time. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) +d1 = pulse.DriveChannel(1) + +with pulse.build() as pulse_prog: + with pulse.align_right(): + # this pulse will start at t=0 + pulse.play(pulse.Constant(100, 1.0), d0) + # this pulse will start at t=80 + pulse.play(pulse.Constant(20, 1.0), d1) +pulse_prog = pulse.transforms.block_to_schedule(pulse_prog) + +assert pulse_prog.ch_stop_time(d0) == pulse_prog.ch_stop_time(d1) +``` + +**Yields** + +None + +**Return type** + +[*AlignmentKind*](#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +### align\_sequential + + + +`qiskit.pulse.builder.align_sequential()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Sequential alignment pulse scheduling context. + +Pulse instructions within this context are scheduled sequentially in time such that no two instructions will be played at the same time. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) +d1 = pulse.DriveChannel(1) + +with pulse.build() as pulse_prog: + with pulse.align_sequential(): + # this pulse will start at t=0 + pulse.play(pulse.Constant(100, 1.0), d0) + # this pulse will also start at t=100 + pulse.play(pulse.Constant(20, 1.0), d1) +pulse_prog = pulse.transforms.block_to_schedule(pulse_prog) + +assert pulse_prog.ch_stop_time(d0) == pulse_prog.ch_start_time(d1) +``` + +**Yields** + +None + +**Return type** + +[*AlignmentKind*](#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +### circuit\_scheduler\_settings + + + +`qiskit.pulse.builder.circuit_scheduler_settings(**settings)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Set the currently active circuit scheduler settings for this context. + + + The function `qiskit.pulse.builder.circuit_scheduler_settings()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was used for gate operations, which are deprecated. pulse schedules should only be used for gate calibrations as part of a quantum circuit, and not vice versa + + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + print(pulse.active_circuit_scheduler_settings()) + with pulse.circuit_scheduler_settings(method='alap'): + print(pulse.active_circuit_scheduler_settings()) +``` + +```python +{} +{'method': 'alap'} +``` + +**Return type** + +[*ContextManager*](https://docs.python.org/3/library/typing.html#typing.ContextManager "(in Python v3.12)")\[None] + +### frequency\_offset + + + +`qiskit.pulse.builder.frequency_offset(frequency, *channels, compensate_phase=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Shift the frequency of inputs channels on entry into context and undo on exit. + +Examples: + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build(backend) as pulse_prog: + # shift frequency by 1GHz + with pulse.frequency_offset(1e9, d0): + pulse.play(pulse.Constant(10, 1.0), d0) + +assert len(pulse_prog.instructions) == 3 + +with pulse.build(backend) as pulse_prog: + # Shift frequency by 1GHz. + # Undo accumulated phase in the shifted frequency frame + # when exiting the context. + with pulse.frequency_offset(1e9, d0, compensate_phase=True): + pulse.play(pulse.Constant(10, 1.0), d0) + +assert len(pulse_prog.instructions) == 4 +``` + +**Parameters** + +* **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Amount of frequency offset in Hz. +* **channels** (*PulseChannel*) – Channels to offset frequency of. +* **compensate\_phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Compensate for accumulated phase accumulated with respect to the channels’ frame at its initial frequency. + +**Yields** + +None + +**Return type** + +[*ContextManager*](https://docs.python.org/3/library/typing.html#typing.ContextManager "(in Python v3.12)")\[None] + +### phase\_offset + + + +`qiskit.pulse.builder.phase_offset(phase, *channels)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Shift the phase of input channels on entry into context and undo on exit. + +Examples: + +```python +import math + +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +with pulse.build() as pulse_prog: + with pulse.phase_offset(math.pi, d0): + pulse.play(pulse.Constant(10, 1.0), d0) + +assert len(pulse_prog.instructions) == 3 +``` + +**Parameters** + +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Amount of phase offset in radians. +* **channels** (*PulseChannel*) – Channels to offset phase of. + +**Yields** + +None + +**Return type** + +[*ContextManager*](https://docs.python.org/3/library/typing.html#typing.ContextManager "(in Python v3.12)")\[None] + +### transpiler\_settings + + + +`qiskit.pulse.builder.transpiler_settings(**settings)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Set the currently active transpiler settings for this context. + + + The function `qiskit.pulse.builder.transpiler_settings()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was used for gate operations, which are deprecated. pulse schedules should only be used for gate calibrations as part of a quantum circuit, and not vice versa + + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + print(pulse.active_transpiler_settings()) + with pulse.transpiler_settings(optimization_level=3): + print(pulse.active_transpiler_settings()) +``` + +```python +{} +{'optimization_level': 3} +``` + +**Return type** + +[*ContextManager*](https://docs.python.org/3/library/typing.html#typing.ContextManager "(in Python v3.12)")\[None] + +### Macros + +Macros help you add more complex functionality to your pulse program. + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeArmonk + +backend = FakeArmonk() + +with pulse.build(backend) as measure_sched: + mem_slot = pulse.measure(0) + print(mem_slot) +``` + +```python +MemorySlot(0) +``` + +### measure + + + +`qiskit.pulse.builder.measure(qubits, registers=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Measure a qubit within the currently active builder context. + +At the pulse level a measurement is composed of both a stimulus pulse and an acquisition instruction which tells the systems measurement unit to acquire data and process it. We provide this measurement macro to automate the process for you, but if desired full control is still available with [`acquire()`](#qiskit.pulse.builder.acquire "qiskit.pulse.builder.acquire") and [`play()`](#qiskit.pulse.builder.play "qiskit.pulse.builder.play"). + +To use the measurement it is as simple as specifying the qubit you wish to measure: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +qubit = 0 + +with pulse.build(backend) as pulse_prog: + # Do something to the qubit. + qubit_drive_chan = pulse.drive_channel(0) + pulse.play(pulse.Constant(100, 1.0), qubit_drive_chan) + # Measure the qubit. + reg = pulse.measure(qubit) +``` + +For now it is not possible to do much with the handle to `reg` but in the future we will support using this handle to a result register to build up ones program. It is also possible to supply this register: + +```python +with pulse.build(backend) as pulse_prog: + pulse.play(pulse.Constant(100, 1.0), qubit_drive_chan) + # Measure the qubit. + mem0 = pulse.MemorySlot(0) + reg = pulse.measure(qubit, mem0) + +assert reg == mem0 +``` + + + Requires the active builder context to have a backend set. + + +**Parameters** + +* **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Physical qubit to measure. +* **registers** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[StorageLocation] | StorageLocation | None*) – Register to store result in. If not selected the current behavior is to return the `MemorySlot` with the same index as `qubit`. This register will be returned. + +**Returns** + +The `register` the qubit measurement result will be stored in. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[StorageLocation] | StorageLocation + +### measure\_all + + + +`qiskit.pulse.builder.measure_all()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Measure all qubits within the currently active builder context. + +A simple macro function to measure all of the qubits in the device at the same time. This is useful for handling device `meas_map` and single measurement constraints. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend) as pulse_prog: + # Measure all qubits and return associated registers. + regs = pulse.measure_all() +``` + + + Requires the active builder context to have a backend set. + + +**Returns** + +The `register`s the qubit measurement results will be stored in. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*MemorySlot*](qiskit.pulse.channels.MemorySlot "qiskit.pulse.channels.MemorySlot")] + +### delay\_qubits + + + +`qiskit.pulse.builder.delay_qubits(duration, *qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Insert delays on all of the `channels.Channel`s that correspond to the input `qubits` at the same time. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse3Q + +backend = FakeOpenPulse3Q() + +with pulse.build(backend) as pulse_prog: + # Delay for 100 cycles on qubits 0, 1 and 2. + regs = pulse.delay_qubits(100, 0, 1, 2) +``` + + + Requires the active builder context to have a backend set. + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration to delay for. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Physical qubits to delay on. Delays will be inserted based on the channels returned by `pulse.qubit_channels()`. + +### Utilities + +The utility functions can be used to gather attributes about the backend and modify how the program is built. + +```python +from qiskit import pulse + +from qiskit.providers.fake_provider import FakeArmonk + +backend = FakeArmonk() + +with pulse.build(backend) as u3_sched: + print('Number of qubits in backend: {}'.format(pulse.num_qubits())) + + samples = 160 + print('There are {} samples in {} seconds'.format( + samples, pulse.samples_to_seconds(160))) + + seconds = 1e-6 + print('There are {} seconds in {} samples.'.format( + seconds, pulse.seconds_to_samples(1e-6))) +``` + +```python +Number of qubits in backend: 1 +There are 160 samples in 3.5555555555555554e-08 seconds +There are 1e-06 seconds in 4500 samples. +``` + +### active\_backend + + + +`qiskit.pulse.builder.active_backend()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Get the backend of the currently active builder context. + +**Returns** + +**The active backend in the currently active** + +builder context. + +**Return type** + +[Backend](qiskit.providers.Backend "qiskit.providers.Backend") + +**Raises** + +[**exceptions.BackendNotSet**](#qiskit.pulse.BackendNotSet "qiskit.pulse.exceptions.BackendNotSet") – If the builder does not have a backend set. + +### active\_transpiler\_settings + + + +`qiskit.pulse.builder.active_transpiler_settings()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return the current active builder context’s transpiler settings. + + + The function `qiskit.pulse.builder.active_transpiler_settings()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was used for gate operations, which are deprecated. pulse schedules should only be used for gate calibrations as part of a quantum circuit, and not vice versa + + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +transpiler_settings = {'optimization_level': 3} + +with pulse.build(backend, + default_transpiler_settings=transpiler_settings): + print(pulse.active_transpiler_settings()) +``` + +```python +{'optimization_level': 3} +``` + +**Return type** + +[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")] + +### active\_circuit\_scheduler\_settings + + + +`qiskit.pulse.builder.active_circuit_scheduler_settings()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return the current active builder context’s circuit scheduler settings. + + + The function `qiskit.pulse.builder.active_circuit_scheduler_settings()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was used for gate operations, which are deprecated. pulse schedules should only be used for gate calibrations as part of a quantum circuit, and not vice versa + + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +circuit_scheduler_settings = {'method': 'alap'} + +with pulse.build( + backend, + default_circuit_scheduler_settings=circuit_scheduler_settings): + print(pulse.active_circuit_scheduler_settings()) +``` + +```python +{'method': 'alap'} +``` + +**Return type** + +[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")] + +### num\_qubits + + + +`qiskit.pulse.builder.num_qubits()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Return number of qubits in the currently active backend. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + print(pulse.num_qubits()) +``` + +```python +2 +``` + + + Requires the active builder context to have a backend set. + + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### qubit\_channels + + + +`qiskit.pulse.builder.qubit_channels(qubit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Returns the set of channels associated with a qubit. + +Examples: + +```python +from qiskit import pulse +from qiskit.providers.fake_provider import FakeOpenPulse2Q + +backend = FakeOpenPulse2Q() + +with pulse.build(backend): + print(pulse.qubit_channels(0)) +``` + +```python +{MeasureChannel(0), ControlChannel(0), DriveChannel(0), AcquireChannel(0), ControlChannel(1)} +``` + + + Requires the active builder context to have a backend set. + + + + A channel may still be associated with another qubit in this list such as in the case where significant crosstalk exists. + + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[*Channel*](#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")] + +### samples\_to\_seconds + + + +`qiskit.pulse.builder.samples_to_seconds(samples)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Obtain the time in seconds that will elapse for the input number of samples on the active backend. + +**Parameters** + +**samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Number of samples to convert to time in seconds. + +**Returns** + +The time that elapses in `samples`. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### seconds\_to\_samples + + + +`qiskit.pulse.builder.seconds_to_samples(seconds)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/builder.py "view source code") + +Obtain the number of samples that will elapse in `seconds` on the active backend. + +Rounds down. + +**Parameters** + +**seconds** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Time in seconds to convert to samples. + +**Returns** + +The number of samples for the time to elapse + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") | [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +## Configuration + +| | | +| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")() | Mapping from [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") [`qiskit.circuit.Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") names and qubits to [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") s. In particular, the mapping is formatted as type::. | + +## Exceptions + +### PulseError + + + +`qiskit.pulse.PulseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/exceptions.py "view source code") + +Errors raised by the pulse module. + +Set the error message. + +### BackendNotSet + + + +`qiskit.pulse.BackendNotSet(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/exceptions.py "view source code") + +Raised if the builder context does not have a backend. + +Set the error message. + +### NoActiveBuilder + + + +`qiskit.pulse.NoActiveBuilder(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/exceptions.py "view source code") + +Raised if no builder context is active. + +Set the error message. + +### UnassignedDurationError + + + +`qiskit.pulse.UnassignedDurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/exceptions.py "view source code") + +Raised if instruction duration is unassigned. + +Set the error message. + +### UnassignedReferenceError + + + +`qiskit.pulse.UnassignedReferenceError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/exceptions.py "view source code") + +Raised if subroutine is unassigned. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/qasm.md b/docs/api/qiskit/0.46/qasm.md new file mode 100644 index 00000000000..43b68c777d1 --- /dev/null +++ b/docs/api/qiskit/0.46/qasm.md @@ -0,0 +1,54 @@ +--- +title: qasm +description: API reference for qiskit.qasm +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.qasm +--- + + + + + + + +# Qasm + + + +`qiskit.qasm` + + + The [`qiskit.qasm`](#module-qiskit.qasm "qiskit.qasm") module has been deprecated and superseded by the [`qiskit.qasm2`](qasm2#module-qiskit.qasm2 "qiskit.qasm2") module which provides a faster more correct parser. + + +## QASM Routines + + + +`qiskit.qasm.Qasm(filename=None, data=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm/qasm.py "view source code") + +OPENQASM circuit object. + +Create an OPENQASM circuit object. + +## Pygments + + + +`qiskit.qasm.OpenQASMLexer(*args, **kwds)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm/pygments/lexer.py "view source code") + +A pygments lexer for OpenQasm. + + + +`qiskit.qasm.QasmHTMLStyle`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm/pygments/lexer.py "view source code") + +A style for OpenQasm in a HTML env (e.g. Jupyter widget). + + + +`qiskit.qasm.QasmTerminalStyle`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm/pygments/lexer.py "view source code") + +A style for OpenQasm in a Terminal env (e.g. Jupyter print). + diff --git a/docs/api/qiskit/0.46/qasm2.md b/docs/api/qiskit/0.46/qasm2.md new file mode 100644 index 00000000000..cb5c866feab --- /dev/null +++ b/docs/api/qiskit/0.46/qasm2.md @@ -0,0 +1,539 @@ +--- +title: qasm2 +description: API reference for qiskit.qasm2 +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.qasm2 +--- + + + + + + + +# OpenQASM 2 + + + +`qiskit.qasm2` + +Qiskit has support for interoperation with OpenQASM 2.0 programs, both [parsing into Qiskit formats](#qasm2-parse) and [exporting back to OpenQASM 2](#qasm2-export). + + + OpenQASM 2 is a simple language, and not suitable for general serialisation of Qiskit objects. See [some discussion of alternatives below](#qasm2-alternatives), if that is what you are looking for. + + + + +## Parsing API + +This module contains two public functions, both of which create a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") from an OpenQASM 2 program. [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") takes a filename, while [`loads()`](#qiskit.qasm2.loads "qiskit.qasm2.loads") takes the program itself as a string. Their internals are very similar, so both offer almost the same API. + +### load + + + +`qiskit.qasm2.load(filename, *, include_path=('.',), include_input_directory='append', custom_instructions=(), custom_classical=(), strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/__init__.py "view source code") + +Parse an OpenQASM 2 program from a file into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). The given path should be ASCII or UTF-8 encoded, and contain the OpenQASM 2 program. + +**Parameters** + +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*PathLike*](https://docs.python.org/3/library/os.html#os.PathLike "(in Python v3.12)")) – The OpenQASM 2 program in a string. +* **include\_path** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*PathLike*](https://docs.python.org/3/library/os.html#os.PathLike "(in Python v3.12)")*]*) – order of directories to search when evaluating `include` statements. +* **include\_input\_directory** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.12)")*\['append', 'prepend'] | None*) – Whether to add the directory of the input file to the `include_path`, and if so, whether to *append* it to search last, or *prepend* it to search first. Pass `None` to suppress adding this directory entirely. +* **custom\_instructions** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*CustomInstruction*](#qiskit.qasm2.CustomInstruction "qiskit.qasm2.parse.CustomInstruction")*]*) – any custom constructors that should be used for specific gates or opaque instructions during circuit construction. See [Specifying custom instructions](#qasm2-custom-instructions) for more. +* **custom\_classical** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*CustomClassical*](#qiskit.qasm2.CustomClassical "qiskit.qasm2.CustomClassical")*]*) – any custom classical functions that should be used during the parsing of classical expressions. See [Specifying custom classical functions](#qasm2-custom-classical) for more. +* **strict** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to run in [strict mode](#qasm2-strict-mode). + +**Returns** + +A circuit object representing the same OpenQASM 2 program. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### loads + + + +`qiskit.qasm2.loads(string, *, include_path=('.',), custom_instructions=(), custom_classical=(), strict=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/__init__.py "view source code") + +Parse an OpenQASM 2 program from a string into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +* **string** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The OpenQASM 2 program in a string. +* **include\_path** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*PathLike*](https://docs.python.org/3/library/os.html#os.PathLike "(in Python v3.12)")*]*) – order of directories to search when evaluating `include` statements. +* **custom\_instructions** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*CustomInstruction*](#qiskit.qasm2.CustomInstruction "qiskit.qasm2.parse.CustomInstruction")*]*) – any custom constructors that should be used for specific gates or opaque instructions during circuit construction. See [Specifying custom instructions](#qasm2-custom-instructions) for more. +* **custom\_classical** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*CustomClassical*](#qiskit.qasm2.CustomClassical "qiskit.qasm2.CustomClassical")*]*) – any custom classical functions that should be used during the parsing of classical expressions. See [Specifying custom classical functions](#qasm2-custom-classical) for more. +* **strict** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to run in [strict mode](#qasm2-strict-mode). + +**Returns** + +A circuit object representing the same OpenQASM 2 program. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Both of these loading functions also take an argument `include_path`, which is an iterable of directory names to use when searching for files in `include` statements. The directories are tried from index 0 onwards, and the first match is used. The import `qelib1.inc` is treated specially; it is always found before looking in the include path, and contains exactly the content of the [paper describing the OpenQASM 2 language](https://arxiv.org/abs/1707.03429). The gates in this include file are mapped to circuit-library gate objects defined by Qiskit. + + + +### Specifying custom instructions + +You can extend the quantum components of the OpenQASM 2 language by passing an iterable of information on custom instructions as the argument `custom_instructions`. In files that have compatible definitions for these instructions, the given `constructor` will be used in place of whatever other handling [`qiskit.qasm2`](#module-qiskit.qasm2 "qiskit.qasm2") would have done. These instructions may optionally be marked as `builtin`, which causes them to not require an `opaque` or `gate` declaration, but they will silently ignore a compatible declaration. Either way, it is an error to provide a custom instruction that has a different number of parameters or qubits as a defined instruction in a parsed program. Each element of the argument iterable should be a particular data class: + + + +`qiskit.qasm2.CustomInstruction(name, num_params, num_qubits, constructor, builtin=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/parse.py "view source code") + +Information about a custom instruction that should be defined during the parse. + +The `name`, `num_params` and `num_qubits` fields are self-explanatory. The `constructor` field should be a callable object with signature `*args -> Instruction`, where each of the `num_params` `args` is a floating-point value. Most of the built-in Qiskit gate classes have this form. + +There is a final `builtin` field. This is optional, and if set true will cause the instruction to be defined and available within the parsing, even if there is no definition in any included OpenQASM 2 file. + +This can be particularly useful when trying to resolve ambiguities in the global-phase conventions of an OpenQASM 2 program. See [OpenQASM 2 Phase Conventions](#qasm2-phase-conventions) for more details. + + + +### Specifying custom classical functions + +Similar to the quantum extensions above, you can also extend the processing done to classical expressions (arguments to gates) by passing an iterable to the argument `custom_classical` to either loader. This needs the `name` (a valid OpenQASM 2 identifier), the number `num_params` of parameters it takes, and a Python callable that implements the function. The Python callable must be able to accept `num_params` positional floating-point arguments, and must return a float or integer (which will be converted to a float). Builtin functions cannot be overridden. + + + +`qiskit.qasm2.CustomClassical` + +Information about a custom classical function that should be defined in mathematical expressions. + +The given callable must be a Python function that takes num\_params floats, and returns a float. The name is the identifier that refers to it in the OpenQASM 2 program. This cannot clash with any defined gates. + + + +### Strict mode + +Both of the loader functions have an optional “strict” mode. By default, this parser is a little bit more relaxed than the official specification: it allows trailing commas in parameter lists; unnecessary (empty-statement) semicolons; the `OPENQASM 2.0;` version statement to be omitted; and a couple of other quality-of-life improvements without emitting any errors. You can use the letter-of-the-spec mode with `strict=True`. + + + +## Exporting API + +Similar to other serialisation modules in Python, this module offers two public functions: [`dump()`](#qiskit.qasm2.dump "qiskit.qasm2.dump") and [`dumps()`](#qiskit.qasm2.dumps "qiskit.qasm2.dumps"), which take a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") and write out a representative OpenQASM 2 program to a file-like object or return a string, respectively. + +### dump + + + +`qiskit.qasm2.dump(circuit, filename_or_stream, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/export.py "view source code") + +Dump a circuit as an OpenQASM 2 program to a file or stream. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") to be exported. +* **filename\_or\_stream** ([*os.PathLike*](https://docs.python.org/3/library/os.html#os.PathLike "(in Python v3.12)") *|*[*io.TextIOBase*](https://docs.python.org/3/library/io.html#io.TextIOBase "(in Python v3.12)")) – either a path-like object (likely a [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") or [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.12)")), or an already opened text-mode stream. + +**Raises** + +[**QASM2ExportError**](#qiskit.qasm2.QASM2ExportError "qiskit.qasm2.QASM2ExportError") – if the circuit cannot be represented by OpenQASM 2. + +### dumps + + + +`qiskit.qasm2.dumps(circuit, /)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/export.py "view source code") + +Export a circuit to an OpenQASM 2 program in a string. + +**Parameters** + +**circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") to be exported. + +**Returns** + +An OpenQASM 2 string representing the circuit. + +**Raises** + +[**QASM2ExportError**](#qiskit.qasm2.QASM2ExportError "qiskit.qasm2.QASM2ExportError") – if the circuit cannot be represented by OpenQASM 2. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +## Errors + +This module defines a generic error type that derives from [`QiskitError`](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") that can be used as a catch when you care about failures emitted by the interoperation layer specifically. + +### QASM2Error + + + +`qiskit.qasm2.QASM2Error(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/exceptions.py "view source code") + +A general error raised by the OpenQASM 2 interoperation layer. + +Set the error message. + +In cases where the lexer or parser fails due to an invalid OpenQASM 2 file, the conversion functions will raise a more specific error with a message explaining what the failure is, and where in the file it occurred. + +### QASM2ParseError + + + +`qiskit.qasm2.QASM2ParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/exceptions.py "view source code") + +An error raised because of a failure to parse an OpenQASM 2 file. + +Set the error message. + +When the exporters fail to export a circuit, likely because it has structure that cannot be represented by OpenQASM 2.0, they will also emit a custom error. + +### QASM2ExportError + + + +`qiskit.qasm2.QASM2ExportError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm2/exceptions.py "view source code") + +An error raised because of a failure to convert a Qiskit object to an OpenQASM 2 form. + +Set the error message. + + + +## Examples + +### Exporting examples + +Export a simple [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") to an OpenQASM 2 string: + +```python +import qiskit.qasm2 +from qiskit.circuit import QuantumCircuit + +qc = QuantumCircuit(2, 2) +qc.h(0) +qc.cx(0, 1) +qc.measure([0, 1], [0, 1]) +print(qiskit.qasm2.dumps(qc)) +``` + +```python +OPENQASM 2.0; +include "qelib1.inc"; +qreg q[2]; +creg c[2]; +h q[0]; +cx q[0],q[1]; +measure q[0] -> c[0]; +measure q[1] -> c[1]; +``` + +Write out the same [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") to a given filename: + +```python +qiskit.qasm2.dump(qc, "myfile.qasm") +``` + +Similarly, one can use general [`os.PathLike`](https://docs.python.org/3/library/os.html#os.PathLike "(in Python v3.12)") instances as the filename: + +```python +import pathlib + +qiskit.qasm2.dump(qc, pathlib.Path.home() / "myfile.qasm") +``` + +One can also dump the text to an already-open stream: + +```python +import io + +with io.StringIO() as stream: + qiskit.qasm2.dump(qc, stream) +``` + +### Parsing examples + +Use [`loads()`](#qiskit.qasm2.loads "qiskit.qasm2.loads") to import an OpenQASM 2 program in a string into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"): + +```python +import qiskit.qasm2 +program = """ + OPENQASM 2.0; + include "qelib1.inc"; + qreg q[2]; + creg c[2]; + + h q[0]; + cx q[0], q[1]; + + measure q -> c; +""" +circuit = qiskit.qasm2.loads(program) +circuit.draw() +``` + +```python + ┌───┐ ┌─┐ +q_0: ┤ H ├──■──┤M├─── + └───┘┌─┴─┐└╥┘┌─┐ +q_1: ─────┤ X ├─╫─┤M├ + └───┘ ║ └╥┘ +c: 2/═══════════╩══╩═ + 0 1 +``` + +You can achieve the same thing if the program is stored in a file by using [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") instead, passing the filename as an argument: + +```python +import qiskit.qasm2 +circuit = qiskit.qasm2.load("myfile.qasm") +``` + +OpenQASM 2 files can include other OpenQASM 2 files via the `include` statement. You can influence the search path used for finding these files with the `include_path` argument to both [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") and [`loads()`](#qiskit.qasm2.loads "qiskit.qasm2.loads"). By default, only the current working directory is searched. + +```python +import qiskit.qasm2 +program = """ + include "other.qasm"; + // ... and so on +""" +circuit = qiskit.qasm2.loads(program, include_path=("/path/to/a", "/path/to/b", ".")) +``` + +For [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") only, there is an extra argument `include_input_directory`, which can be used to either `'append'`, `'prepend'` or ignore (`None`) the directory of the loaded file in the include path. By default, this directory is appended to the search path, so it is tried last, but you can change this. + +```python +import qiskit.qasm2 +filenames = ["./subdirectory/a.qasm", "/path/to/b.qasm", "~/my.qasm"] +# Search the directory of each file before other parts of the include path. +circuits = [ + qiskit.qasm2.load(filename, include_input_directory="prepend") for filename in filenames +] +# Override the include path, and don't search the directory of each file unless it's in the +# absolute path list. +circuits = [ + qiskit.qasm2.load( + filename, + include_path=("/usr/include/qasm", "~/qasm/include"), + include_input_directory=None, + ) + for filename in filenames +] +``` + +Sometimes you may want to influence the [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") objects that the importer emits for given named instructions. Gates that are defined by the statement `include "qelib1.inc";` will automatically be associated with a suitable Qiskit circuit-library gate, but you can extend this: + +```python +from qiskit.circuit import Gate +from qiskit.qasm2 import loads, CustomInstruction + +class MyGate(Gate): + def __init__(self, theta): + super().__init__("my", 2, [theta]) + +class Builtin(Gate): + def __init__(self): + super().__init__("builtin", 1, []) + +program = """ + opaque my(theta) q1, q2; + qreg q[2]; + my(0.5) q[0], q[1]; + builtin q[0]; +""" +customs = [ + CustomInstruction(name="my", num_params=1, num_qubits=2, constructor=MyGate), + # Setting 'builtin=True' means the instruction doesn't require a declaration to be usable. + CustomInstruction("builtin", 0, 1, Builtin, builtin=True), +] +circuit = loads(program, custom_instructions=customs) +``` + +Similarly, you can add new classical functions used during the description of arguments to gates, both in the main body of the program (which come out constant-folded) and within the bodies of defined gates (which are computed on demand). Here we provide a Python version of `atan2(y, x)`, which mathematically is $\arctan(y/x)$ but correctly handling angle quadrants and infinities, and a custom `add_one` function: + +```python +import math +from qiskit.qasm2 import loads, CustomClassical + +program = """ + include "qelib1.inc"; + qreg q[2]; + rx(atan2(pi, 3 + add_one(0.2))) q[0]; + cx q[0], q[1]; +""" + +def add_one(x): + return x + 1 + +customs = [ + # `atan2` takes two parameters, and `math.atan2` implements it. + CustomClassical("atan2", 2, math.atan2), + # Our `add_one` takes only one parameter. + CustomClassical("add_one", 1, add_one), +] +circuit = loads(program, custom_classical=customs) +``` + + + +## OpenQASM 2 Phase Conventions + +As a language, OpenQASM 2 does not have a way to specify the global phase of a complete program, nor of particular gate definitions. This means that parsers of the language may interpret particular gates with a different global phase than what you might expect. For example, the *de facto* standard library of OpenQASM 2 `qelib1.inc` contains definitions of `u1` and `rz` as follows: + +```python +gate u1(lambda) q { + U(0, 0, lambda) q; +} + +gate rz(phi) a { + u1(phi) a; +} +``` + +In other words, `rz` appears to be a direct alias for `u1`. However, the interpretation of `u1` is specified in [equation (3) of the paper describing the language](https://arxiv.org/abs/1707.03429) as + +$$ +u_1(\lambda) = \operatorname{diag}\bigl(1, e^{i\lambda}\bigr) \sim R_z(\lambda) +$$ + +where the $\sim$ symbol denotes equivalence only up to a global phase. When parsing OpenQASM 2, we need to choose how to handle a distinction between such gates; `u1` is defined in the prose to be different by a phase to `rz`, but the language is not designed to represent this. + +Qiskit’s default position is to interpret a usage of the standard-library `rz` using [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate"), and a usage of `u1` as using the phase-distinct [`U1Gate`](qiskit.circuit.library.U1Gate "qiskit.circuit.library.U1Gate"). If you wish to use the phase conventions more implied by a direct interpretation of the `gate` statements in the header file, you can use [`CustomInstruction`](#qiskit.qasm2.CustomInstruction "qiskit.qasm2.CustomInstruction") to override how Qiskit builds the circuit. + +For the standard `qelib1.inc` include there is only one point of difference, and so the override needed to switch its phase convention is: + +```python +from qiskit import qasm2 +from qiskit.circuit.library import PhaseGate +from qiskit.quantum_info import Operator + +program = """ + OPENQASM 2.0; + include "qelib1.inc"; + qreg q[1]; + rz(pi / 2) q[0]; +""" + +custom = [ + qasm2.CustomInstruction("rz", 1, 1, PhaseGate), +] +``` + +This will use Qiskit’s [`PhaseGate`](qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") class to represent the `rz` instruction, which is equal (including the phase) to [`U1Gate`](qiskit.circuit.library.U1Gate "qiskit.circuit.library.U1Gate"): + +```python +Operator(qasm2.loads(program, custom_instructions=custom)) +``` + +```python +Operator([[1.000000e+00+0.j, 0.000000e+00+0.j], + [0.000000e+00+0.j, 6.123234e-17+1.j]], + input_dims=(2,), output_dims=(2,)) +``` + + + +## Legacy Compatibility + +[`QuantumCircuit.from_qasm_str()`](qiskit.circuit.QuantumCircuit#from_qasm_str "qiskit.circuit.QuantumCircuit.from_qasm_str") and [`from_qasm_file()`](qiskit.circuit.QuantumCircuit#from_qasm_file "qiskit.circuit.QuantumCircuit.from_qasm_file") used to make a few additions on top of the raw specification. Qiskit originally tried to use OpenQASM 2 as a sort of serialisation format, and expanded its behaviour as Qiskit expanded. The new parser under all its defaults implements the specification more strictly. + +The complete legacy code-paths are + +```python +from qiskit.converters import ast_to_dag, dag_to_circuit +from qiskit.qasm import Qasm + +def from_qasm_file(path: str): + dag_to_circuit(ast_to_dag(Qasm(filename=path).parse())) + +def from_qasm_str(qasm_str: str): + dag_to_circuit(ast_to_dag(Qasm(data=qasm_str).parse())) +``` + +In particular, in the legacy importers: + +* **the include\_path is effectively:** + + 1. `/qasm/libs`, where `` is the root of the installed `qiskit` package; + 2. the current working directory. + +* **there are additional instructions defined in `qelib1.inc`:** + + **`csx a, b`** + + Controlled $\sqrt X$ gate, corresponding to [`CSXGate`](qiskit.circuit.library.CSXGate "qiskit.circuit.library.CSXGate"). + + **`cu(theta, phi, lambda, gamma) c, t`** + + The four-parameter version of a controlled-$U$, corresponding to [`CUGate`](qiskit.circuit.library.CUGate "qiskit.circuit.library.CUGate"). + + **`rxx(theta) a, b`** + + Two-qubit rotation around the $XX$ axis, corresponding to [`RXXGate`](qiskit.circuit.library.RXXGate "qiskit.circuit.library.RXXGate"). + + **`rzz(theta) a, b`** + + Two-qubit rotation around the $ZZ$ axis, corresponding to [`RZZGate`](qiskit.circuit.library.RZZGate "qiskit.circuit.library.RZZGate"). + + **`rccx a, b, c`** + + The double-controlled $X$ gate, but with relative phase differences over the standard Toffoli gate. This *should* correspond to the Qiskit gate [`RCCXGate`](qiskit.circuit.library.RCCXGate "qiskit.circuit.library.RCCXGate"), but the legacy converter wouldn’t actually output this type. + + **`rc3x a, b, c, d`** + + The triple-controlled $X$ gate, but with relative phase differences over the standard definition. Corresponds to [`RC3XGate`](qiskit.circuit.library.RC3XGate "qiskit.circuit.library.RC3XGate"). + + **`c3x a, b, c, d`** + + The triple-controlled $X$ gate, corresponding to [`C3XGate`](qiskit.circuit.library.C3XGate "qiskit.circuit.library.C3XGate"). + + **`c3sqrtx a, b, c, d`** + + The triple-controlled $\sqrt X$ gate, corresponding to [`C3SXGate`](qiskit.circuit.library.C3SXGate "qiskit.circuit.library.C3SXGate"). + + **`c4x a, b, c, d, e`** + + The quadruple-controlled $X$ gate., corresponding to [`C4XGate`](qiskit.circuit.library.C4XGate "qiskit.circuit.library.C4XGate"). + +* if *any* `opaque` or `gate` definition was given for the name `delay`, they attempt to output a [`Delay`](qiskit.circuit.Delay "qiskit.circuit.Delay") instruction at each call. To function, this expects a definition compatible with `opaque delay(t) q;`, where the time `t` is given in units of `dt`. The importer will raise errors on construction if there was not exactly one parameter and one qubit, or if the parameter is not integer-valued. + +* the additional scientific-calculator functions `asin`, `acos` and `atan` are available. + +* the parsed grammar is effectively the same as [the strict mode of the new importers](#qasm2-strict-mode). + +You can emulate this behaviour in [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") and [`loads()`](#qiskit.qasm2.loads "qiskit.qasm2.loads") by setting include\_path appropriately (try inspecting the variable `qiskit.__file__` to find the installed location), and by passing a list of [`CustomInstruction`](#qiskit.qasm2.CustomInstruction "qiskit.qasm2.CustomInstruction") instances for each of the custom gates you care about. To make things easier we make three tuples available, which each contain one component of a configuration that is equivalent to Qiskit’s legacy converter behaviour. + +**qiskit.qasm2.LEGACY\_CUSTOM\_INSTRUCTIONS** + +A tuple containing the extra custom\_instructions that Qiskit’s legacy built-in converters used if `qelib1.inc` is included, and there is any definition of a `delay` instruction. The gates in the paper version of `qelib1.inc` and `delay` all require a compatible declaration statement to be present within the OpenQASM 2 program, but Qiskit’s legacy additions are all marked as builtins since they are not actually present in any include file this parser sees. + +**qiskit.qasm2.LEGACY\_CUSTOM\_CLASSICAL** + +A tuple containing the extra custom\_classical functions that Qiskit’s legacy built-in converters use beyond those specified by the paper. This is the three basic inverse trigonometric functions: $\asin$, $\acos$ and $\atan$. + +**qiskit.qasm2.LEGACY\_INCLUDE\_PATH** + +A tuple containing the exact include\_path used by the legacy Qiskit converter. + +On *all* the gates defined in Qiskit’s legacy version of `qelib1.inc` and the `delay` instruction, it does not matter how the gates are actually defined and used, the legacy importer will always attempt to output its custom objects for them. This can result in errors during the circuit construction, even after a successful parse. There is no way to emulate this buggy behaviour with [`qiskit.qasm2`](#module-qiskit.qasm2 "qiskit.qasm2"); only an `include "qelib1.inc";` statement or the custom\_instructions argument can cause built-in Qiskit instructions to be used, and the signatures of these match each other. + + + Circuits imported with [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") and [`loads()`](#qiskit.qasm2.loads "qiskit.qasm2.loads") with the above legacy-compatibility settings should compare equal to those created by Qiskit’s legacy importer, provided no non-`qelib1.inc` user gates are defined. User-defined gates are handled slightly differently in the new importer, and while they should have equivalent [`definition`](qiskit.circuit.Instruction#definition "qiskit.circuit.Instruction.definition") fields on inspection, this module uses a custom class to lazily load the definition when it is requested (like most Qiskit objects), rather than eagerly creating it during the parse. Qiskit’s comparison rules for gates will see these two objects as unequal, although any pass through [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") for a particular backend should produce the same output circuits. + + + + +## Alternatives + +The parser components of this module started off as a separate PyPI package: [qiskit-qasm2](https://pypi.org/project/qiskit-qasm2/). This package at version 0.5.3 was vendored into Qiskit Terra 0.24. Any subsequent changes between the two packages may not necessarily be kept in sync. + +There is a newer version of the OpenQASM specification, version 3.0, which is described at [https://openqasm.com](https://openqasm.com). This includes far more facilities for high-level classical programming. Qiskit has some rudimentary support for OpenQASM 3 already; see [`qiskit.qasm3`](qasm3#module-qiskit.qasm3 "qiskit.qasm3") for that. + +OpenQASM 2 is not a suitable serialization language for Qiskit’s [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). This module is provided for interoperability purposes, not as a general serialization format. If that is what you need, consider using [`qiskit.qpy`](qpy#module-qiskit.qpy "qiskit.qpy") instead. + diff --git a/docs/api/qiskit/0.46/qasm3.md b/docs/api/qiskit/0.46/qasm3.md new file mode 100644 index 00000000000..dfedb2c5339 --- /dev/null +++ b/docs/api/qiskit/0.46/qasm3.md @@ -0,0 +1,299 @@ +--- +title: qasm3 +description: API reference for qiskit.qasm3 +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.qasm3 +--- + + + + + + + +# OpenQASM 3 + + + +`qiskit.qasm3` + +Qiskit provides some tools for converting between [OpenQASM 3](https://openqasm.com) representations of quantum programs, and the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") class. These will continue to evolve as Qiskit’s support for the dynamic-circuit capabilities expressed by OpenQASM 3 increases. + +## Exporting to OpenQASM 3 + +The high-level functions are simply [`dump()`](#qiskit.qasm3.dump "qiskit.qasm3.dump") and [`dumps()`](#qiskit.qasm3.dumps "qiskit.qasm3.dumps"), which respectively export to a file (given as a filename) and to a Python string. + +### dump + + + +`qiskit.qasm3.dump(circuit, stream, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/__init__.py "view source code") + +Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object as an OpenQASM 3 stream to file-like object. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Circuit to serialize. +* **stream** (*TextIOBase*) – stream-like object to dump the OpenQASM 3 serialization +* **\*\*kwargs** – Arguments for the [`Exporter`](#qiskit.qasm3.Exporter "qiskit.qasm3.Exporter") constructor. + +### dumps + + + +`qiskit.qasm3.dumps(circuit, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/__init__.py "view source code") + +Serialize a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object in an OpenQASM 3 string. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Circuit to serialize. +* **\*\*kwargs** – Arguments for the [`Exporter`](#qiskit.qasm3.Exporter "qiskit.qasm3.Exporter") constructor. + +**Returns** + +The OpenQASM 3 serialization + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +Both of these exporter functions are single-use wrappers around the main [`Exporter`](#qiskit.qasm3.Exporter "qiskit.qasm3.Exporter") class. For more complex exporting needs, including dumping multiple circuits in a single session, it may be more convenient or faster to use the complete interface. + + + +`qiskit.qasm3.Exporter(includes=('stdgates.inc', ), basis_gates=('U', ), disable_constants=False, alias_classical_registers=None, allow_aliasing=None, indent='  ', experimental=ExperimentalFeatures.None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/exporter.py "view source code") + +QASM3 exporter main class. + +**Parameters** + +* **includes** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – the filenames that should be emitted as includes. These files will be parsed for gates, and any objects dumped from this exporter will use those definitions where possible. + +* **basis\_gates** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – the basic defined gate set of the backend. + +* **disable\_constants** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True`, always emit floating-point constants for numeric parameter values. If `False` (the default), then values close to multiples of OpenQASM 3 constants (`pi`, `euler`, and `tau`) will be emitted in terms of those constants instead, potentially improving accuracy in the output. + +* **alias\_classical\_registers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – + + If `True`, then bits may be contained in more than one register. If so, the registers will be emitted using “alias” definitions, which might not be well supported by consumers of OpenQASM 3. + + + **Parameter `allow_aliasing`** + + A value for `allow_aliasing` overrides any value given here, and supersedes this parameter. + + +* **allow\_aliasing** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – + + If `True`, then bits may be contained in more than one register. If so, the registers will be emitted using “alias” definitions, which might not be well supported by consumers of OpenQASM 3. Defaults to `False` or the value of `alias_classical_registers`. + + New in version 0.25.0. + +* **indent** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the indentation string to use for each level within an indented block. Can be set to the empty string to disable indentation. + +* **experimental** ([*ExperimentalFeatures*](#qiskit.qasm3.ExperimentalFeatures "qiskit.qasm3.experimental.ExperimentalFeatures")) – any experimental features to enable during the export. See [`ExperimentalFeatures`](#qiskit.qasm3.ExperimentalFeatures "qiskit.qasm3.ExperimentalFeatures") for more details. + +### dump + + + +`dump(circuit, stream)` + +Convert the circuit to OpenQASM 3, dumping the result to a file or text stream. + +### dumps + + + +`dumps(circuit)` + +Convert the circuit to OpenQASM 3, returning the result as a string. + +All of these interfaces will raise [`QASM3ExporterError`](#qiskit.qasm3.QASM3ExporterError "qiskit.qasm3.QASM3ExporterError") on failure. + +### QASM3ExporterError + + + +`qiskit.qasm3.QASM3ExporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/exceptions.py "view source code") + +An error raised during running the OpenQASM 3 exporter. + +Set the error message. + +### Experimental features + +The OpenQASM 3 language is still evolving as hardware capabilities improve, so there is no final syntax that Qiskit can reliably target. In order to represent the evolving language, we will sometimes release features before formal standardization, which may need to change as the review process in the OpenQASM 3 design committees progresses. By default, the exporters will only support standardised features of the language. To enable these early-release features, use the `experimental` keyword argument of [`dump()`](#qiskit.qasm3.dump "qiskit.qasm3.dump") and [`dumps()`](#qiskit.qasm3.dumps "qiskit.qasm3.dumps"). The available feature flags are: + + + +`qiskit.qasm3.ExperimentalFeatures(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/experimental.py "view source code") + +Flags for experimental features that the OpenQASM 3 exporter supports. + +These are experimental and are more liable to change, because the OpenQASM 3 specification has not formally accepted them yet, so the syntax may not be finalized. + + + +### SWITCH\_CASE\_V1 + +`= 1` + +Support exporting switch-case statements as proposed by [https://github.com/openqasm/openqasm/pull/463](https://github.com/openqasm/openqasm/pull/463) at [commit bfa787aa3078](https://github.com/openqasm/openqasm/pull/463/commits/bfa787aa3078). + +If you want to enable multiple experimental features, you should combine the flags using the `|` operator, such as `flag1 | flag2`. + +For example, to perform an export using the early semantics of `switch` support: + +```python +from qiskit import qasm3, QuantumCircuit, QuantumRegister, ClassicalRegister + +# Build the circuit +qreg = QuantumRegister(3) +creg = ClassicalRegister(3) +qc = QuantumCircuit(qreg, creg) +with qc.switch(creg) as case: + with case(0): + qc.x(0) + with case(1, 2): + qc.x(1) + with case(case.DEFAULT): + qc.x(2) + +# Export to an OpenQASM 3 string. +qasm_string = qasm3.dumps(qc, experimental=qasm3.ExperimentalFeatures.SWITCH_CASE_V1) +``` + + + All features enabled by the experimental flags are naturally transient. If it becomes necessary to remove flags, they will be subject to [the standard Qiskit deprecation policy](https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md). We will leave these experimental flags in place for as long as is reasonable. + + However, we cannot guarantee any support windows for *consumers* of OpenQASM 3 code generated using these experimental flags, if the OpenQASM 3 language specification changes the proposal that the flag is based on. It is possible that any tool you are using to consume OpenQASM 3 code created using these flags may update or remove their support while Qiskit continues to offer the flag. You should not rely on the resultant experimental OpenQASM 3 code for long-term storage of programs. + + +## Importing from OpenQASM 3 + +Currently only two high-level functions are offered, as Qiskit support for importing from OpenQASM 3 is in its infancy, and the implementation is expected to change significantly. The two functions are [`load()`](#qiskit.qasm3.load "qiskit.qasm3.load") and [`loads()`](#qiskit.qasm3.loads "qiskit.qasm3.loads"), which are direct counterparts of [`dump()`](#qiskit.qasm3.dump "qiskit.qasm3.dump") and [`dumps()`](#qiskit.qasm3.dumps "qiskit.qasm3.dumps"), respectively loading a program indirectly from a named file and directly from a given string. + + + While we are still in the exploratory release period, to use either function, the package `qiskit_qasm3_import` must be installed. This can be done by installing Qiskit Terra with the `qasm3-import` extra, such as by: + + ```python + pip install qiskit-terra[qasm3-import] + ``` + + We expect that this functionality will eventually be merged into core Terra, and no longer require an optional import, but we do not yet have a timeline for this. + + +### load + + + +`qiskit.qasm3.load(filename)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/__init__.py "view source code") + +Load an OpenQASM 3 program from the file `filename`. + +**Parameters** + +**filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the filename to load the program from. + +**Returns** + +a circuit representation of the OpenQASM 3 program. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QASM3ImporterError**](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") – if the OpenQASM 3 file is invalid, or cannot be represented by a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +### loads + + + +`qiskit.qasm3.loads(program)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/__init__.py "view source code") + +Load an OpenQASM 3 program from the given string. + +**Parameters** + +**program** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the OpenQASM 3 program. + +**Returns** + +a circuit representation of the OpenQASM 3 program. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QASM3ImporterError**](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") – if the OpenQASM 3 file is invalid, or cannot be represented by a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +Both of these two functions raise [`QASM3ImporterError`](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") on failure. + +### QASM3ImporterError + + + +`qiskit.qasm3.QASM3ImporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qasm3/exceptions.py "view source code") + +An error raised during the OpenQASM 3 importer. + +Set the error message. + +For example, we can define a quantum program using OpenQASM 3, and use [`loads()`](#qiskit.qasm3.loads "qiskit.qasm3.loads") to directly convert it into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"): + +```python +import qiskit.qasm3 + +program = """ + OPENQASM 3.0; + include "stdgates.inc"; + + input float[64] a; + qubit[3] q; + bit[2] mid; + bit[3] out; + + let aliased = q[0:1]; + + gate my_gate(a) c, t { + gphase(a / 2); + ry(a) c; + cx c, t; + } + gate my_phase(a) c { + ctrl @ inv @ gphase(a) c; + } + + my_gate(a * 2) aliased[0], q[{1, 2}][0]; + measure q[0] -> mid[0]; + measure q[1] -> mid[1]; + + while (mid == "00") { + reset q[0]; + reset q[1]; + my_gate(a) q[0], q[1]; + my_phase(a - pi/2) q[1]; + mid[0] = measure q[0]; + mid[1] = measure q[1]; + } + + if (mid[0]) { + let inner_alias = q[{0, 1}]; + reset inner_alias; + } + + out = measure q; +""" +circuit = qiskit.qasm3.loads(program) +circuit.draw("mpl") +``` + +![../\_images/qasm3-1.png](/images/api/qiskit/0.46/qasm3-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AlgorithmJob.md b/docs/api/qiskit/0.46/qiskit.algorithms.AlgorithmJob.md new file mode 100644 index 00000000000..1c28c725869 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AlgorithmJob.md @@ -0,0 +1,168 @@ +--- +title: AlgorithmJob +description: API reference for qiskit.algorithms.AlgorithmJob +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AlgorithmJob +--- + +# AlgorithmJob + + + +`qiskit.algorithms.AlgorithmJob(function, *args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/algorithm_job.py "view source code") + +Bases: `PrimitiveJob` + +This empty class is introduced for typing purposes. + +**Parameters** + +**function** – a callable function to execute the job. + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backend + + + +`backend()` + +Return the backend where this job was executed. + +**Return type** + +[*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") + +### cancel + + + +`cancel()` + +Attempt to cancel the job. + +### cancelled + + + +`cancelled()` + +Return whether the job has been cancelled. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### done + + + +`done()` + +Return whether the job has successfully run. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### in\_final\_state + + + +`in_final_state()` + +Return whether the job is in a final job state such as `DONE` or `ERROR`. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### job\_id + + + +`job_id()` + +Return a unique id identifying the job. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### result + + + +`result()` + +Return the results of the job. + +**Return type** + +*T* + +### running + + + +`running()` + +Return whether the job is actively running. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### status + + + +`status()` + +Return the status of the job, among the values of `JobStatus`. + +### submit + + + +`submit()` + +Submit the job to the backend for execution. + +### wait\_for\_final\_state + + + +`wait_for_final_state(timeout=None, wait=5, callback=None)` + +Poll the job status until it progresses to a final state such as `DONE` or `ERROR`. + +**Parameters** + +* **timeout** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Seconds to wait for the job. If `None`, wait indefinitely. + +* **wait** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Seconds between queries. + +* **callback** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – + + Callback function invoked after each query. The following positional arguments are provided to the callback function: + + * job\_id: Job ID + * job\_status: Status of the job from the last query + * job: This BaseJob instance + + Note: different subclass might provide different arguments to the callback function. + +**Raises** + +[**JobTimeoutError**](providers#qiskit.providers.JobTimeoutError "qiskit.providers.JobTimeoutError") – If the job does not reach a final state before the specified timeout. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AmplificationProblem.md b/docs/api/qiskit/0.46/qiskit.algorithms.AmplificationProblem.md new file mode 100644 index 00000000000..426a92036ac --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AmplificationProblem.md @@ -0,0 +1,93 @@ +--- +title: AmplificationProblem +description: API reference for qiskit.algorithms.AmplificationProblem +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AmplificationProblem +--- + +# AmplificationProblem + + + +`qiskit.algorithms.AmplificationProblem(oracle, state_preparation=None, grover_operator=None, post_processing=None, objective_qubits=None, is_good_state=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_amplifiers/amplification_problem.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +The amplification problem is the input to amplitude amplification algorithms, like Grover. + +This class contains all problem-specific information required to run an amplitude amplification algorithm. It minimally contains the Grover operator. It can further hold some post processing on the optimal bitstring. + +**Parameters** + +* **oracle** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – The oracle reflecting about the bad states. +* **state\_preparation** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A circuit preparing the input state, referred to as $\mathcal{A}$. If None, a layer of Hadamard gates is used. +* **grover\_operator** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – The Grover operator $\mathcal{Q}$ used as unitary in the phase estimation circuit. If None, this operator is constructed from the `oracle` and `state_preparation`. +* **post\_processing** (*Callable\[\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*], Any] | None*) – A mapping applied to the most likely bitstring. +* **objective\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – If set, specifies the indices of the qubits that should be measured. If None, all qubits will be measured. The `is_good_state` function will be applied on the measurement outcome of these qubits. +* **is\_good\_state** (*Callable\[\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*],* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] |* [*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *| None*) – A function to check whether a string represents a good state. By default if the `oracle` argument has an `evaluate_bitstring` method (currently only provided by the [`PhaseOracle`](qiskit.circuit.library.PhaseOracle "qiskit.circuit.library.PhaseOracle") class) this will be used, otherwise this kwarg is required and **must** be specified. + +## Attributes + + + +### grover\_operator + +Get the $\mathcal{Q}$ operator, or Grover operator. + +If the Grover operator is not set, we try to build it from the $\mathcal{A}$ operator and objective\_qubits. This only works if objective\_qubits is a list of integers. + +**Returns** + +The Grover operator, or None if neither the Grover operator nor the $\mathcal{A}$ operator is set. + + + +### is\_good\_state + +Check whether a provided bitstring is a good state or not. + +**Returns** + +A callable that takes in a bitstring and returns True if the measurement is a good state, False otherwise. + + + +### objective\_qubits + +The indices of the objective qubits. + +**Returns** + +The indices of the objective qubits as list of integers. + + + +### oracle + +Return the oracle. + +**Returns** + +The oracle. + + + +### post\_processing + +Apply post processing to the input value. + +**Returns** + +A handle to the post processing function. Acts as identity by default. + + + +### state\_preparation + +Get the state preparation operator $\mathcal{A}$. + +**Returns** + +The $\mathcal{A}$ operator as QuantumCircuit. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeAmplifier.md b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeAmplifier.md new file mode 100644 index 00000000000..4b14d938e73 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeAmplifier.md @@ -0,0 +1,40 @@ +--- +title: AmplitudeAmplifier +description: API reference for qiskit.algorithms.AmplitudeAmplifier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AmplitudeAmplifier +--- + +# AmplitudeAmplifier + + + +`qiskit.algorithms.AmplitudeAmplifier`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_amplifiers/amplitude_amplifier.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +The interface for amplification algorithms. + +## Methods + +### amplify + + + +`abstract amplify(amplification_problem)` + +Run the amplification algorithm. + +**Parameters** + +**amplification\_problem** ([*AmplificationProblem*](qiskit.algorithms.AmplificationProblem "qiskit.algorithms.amplitude_amplifiers.amplification_problem.AmplificationProblem")) – The amplification problem. + +**Returns** + +The result as a `AmplificationResult`, where e.g. the most likely state can be queried as `result.top_measurement`. + +**Return type** + +*AmplitudeAmplifierResult* + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimation.md new file mode 100644 index 00000000000..c844fb460d4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimation.md @@ -0,0 +1,209 @@ +--- +title: AmplitudeEstimation +description: API reference for qiskit.algorithms.AmplitudeEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AmplitudeEstimation +--- + +# AmplitudeEstimation + + + +`qiskit.algorithms.AmplitudeEstimation(num_eval_qubits, phase_estimation_circuit=None, iqft=None, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/ae.py "view source code") + +Bases: [`AmplitudeEstimator`](qiskit.algorithms.AmplitudeEstimator "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimator") + +The Quantum Phase Estimation-based Amplitude Estimation algorithm. + +This class implements the original Quantum Amplitude Estimation (QAE) algorithm, introduced by \[1]. This canonical version uses quantum phase estimation along with a set of $m$ additional evaluation qubits to find an estimate $\tilde{a}$, that is restricted to the grid + +$$ +\tilde{a} \in \{\sin^2(\pi y / 2^m) : y = 0, ..., 2^{m-1}\} +$$ + +More evaluation qubits produce a finer sampling grid, therefore the accuracy of the algorithm increases with $m$. + +Using a maximum likelihood post processing, this grid constraint can be circumvented. This improved estimator is implemented as well, see \[2] Appendix A for more detail. + + + This class does not support the [`EstimationProblem.is_good_state`](qiskit.algorithms.EstimationProblem#is_good_state "qiskit.algorithms.EstimationProblem.is_good_state") property, as for phase estimation-based QAE, the oracle that identifes the good states must be encoded in the Grover operator. To set custom oracles, the [`EstimationProblem.grover_operator`](qiskit.algorithms.EstimationProblem#grover_operator "qiskit.algorithms.EstimationProblem.grover_operator") attribute can be set directly. + + +**References** + +**\[1]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000).** + +Quantum Amplitude Amplification and Estimation. [arXiv:quant-ph/0005055](http://arxiv.org/abs/quant-ph/0005055). + +**\[2]: Grinko, D., Gacon, J., Zoufal, C., & Woerner, S. (2019).** + +Iterative Quantum Amplitude Estimation. [arXiv:1912.05559](https://arxiv.org/abs/1912.05559). + + + `qiskit.algorithms.amplitude_estimators.ae.AmplitudeEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **num\_eval\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of evaluation qubits. +* **phase\_estimation\_circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – The phase estimation circuit used to run the algorithm. Defaults to the standard phase estimation circuit from the circuit library, qiskit.circuit.library.PhaseEstimation when None. +* **iqft** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – The inverse quantum Fourier transform component, defaults to using a standard implementation from qiskit.circuit.library.QFT when None. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: The backend (or QuantumInstance) to execute the circuits on. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – A sampler primitive to evaluate the circuits. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the number of evaluation qubits is smaller than 1. + +## Attributes + + + +### quantum\_instance + +Get the quantum instance. + + + The property `qiskit.algorithms.amplitude_estimators.ae.AmplitudeEstimation.quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Returns** + +The quantum instance used to run this algorithm. + +**Type** + +Deprecated + + + +### sampler + +Get the sampler primitive. + +**Returns** + +The sampler primitive to evaluate the circuits. + +## Methods + +### compute\_confidence\_interval + + + +`static compute_confidence_interval(result, alpha=0.05, kind='likelihood_ratio')` + +Compute the (1 - alpha) confidence interval. + +**Parameters** + +* **result** ([*AmplitudeEstimationResult*](qiskit.algorithms.AmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.ae.AmplitudeEstimationResult")) – An amplitude estimation result for which to compute the confidence interval. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Confidence level: compute the (1 - alpha) confidence interval. +* **kind** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The method to compute the confidence interval, can be ‘fisher’, ‘observed\_fisher’ or ‘likelihood\_ratio’ (default) + +**Returns** + +The (1 - alpha) confidence interval of the specified kind. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If the confidence interval method kind is not implemented. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### compute\_mle + + + +`static compute_mle(result, apply_post_processing=False)` + +Compute the Maximum Likelihood Estimator (MLE). + +**Parameters** + +* **result** ([*AmplitudeEstimationResult*](qiskit.algorithms.AmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.ae.AmplitudeEstimationResult")) – An amplitude estimation result object. +* **apply\_post\_processing** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, apply the post processing to the MLE before returning it. + +**Returns** + +The MLE for the provided result object. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### construct\_circuit + + + +`construct_circuit(estimation_problem, measurement=False)` + +Construct the Amplitude Estimation quantum circuit. + +**Parameters** + +* **estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem for which to construct the QAE circuit. +* **measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Boolean flag to indicate if measurements should be included in the circuit. + +**Returns** + +The QuantumCircuit object for the constructed circuit. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### estimate + + + +`estimate(estimation_problem)` + +Run the amplitude estimation algorithm on provided estimation problem. + +**Parameters** + +**estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem. + +**Returns** + +An amplitude estimation results object. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If state\_preparation or objective\_qubits are not set in the estimation\_problem. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – A quantum instance or sampler must be provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – Sampler job run error. + +**Return type** + +[*AmplitudeEstimationResult*](qiskit.algorithms.AmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.ae.AmplitudeEstimationResult") + +### evaluate\_measurements + + + +`evaluate_measurements(circuit_results, threshold=1e-06)` + +Evaluate the results from the circuit simulation. + +Given the probabilities from statevector simulation of the QAE circuit, compute the probabilities that the measurements y/gridpoints a are the best estimate. + +**Parameters** + +* **circuit\_results** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | np.ndarray*) – The circuit result from the QAE circuit. Can be either a counts dict or a statevector or a quasi-probabilities dict. +* **threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Measurements with probabilities below the threshold are discarded. + +**Returns** + +**Dictionaries containing the a gridpoints with respective probabilities and** + +y measurements with respective probabilities, in this order. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")], [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimationResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimationResult.md new file mode 100644 index 00000000000..80b08e2a4dd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimationResult.md @@ -0,0 +1,124 @@ +--- +title: AmplitudeEstimationResult +description: API reference for qiskit.algorithms.AmplitudeEstimationResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AmplitudeEstimationResult +--- + +# AmplitudeEstimationResult + + + +`qiskit.algorithms.AmplitudeEstimationResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/ae.py "view source code") + +Bases: [`AmplitudeEstimatorResult`](qiskit.algorithms.AmplitudeEstimatorResult "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimatorResult") + +The `AmplitudeEstimation` result object. + +## Attributes + + + +### circuit\_results + +Return the circuit results. Can be a statevector or counts dictionary. + + + +### confidence\_interval + +Return the confidence interval for the amplitude (95% interval by default). + + + +### confidence\_interval\_processed + +Return the post-processed confidence interval (95% interval by default). + + + +### estimation + +Return the estimation for the amplitude in $[0, 1]$. + + + +### estimation\_processed + +Return the estimation for the amplitude after the post-processing has been applied. + + + +### max\_probability + +Return the maximum sampling probability. + + + +### measurements + +Return the measurements as integers with their measurement probability. + + + +### mle + +Return the MLE for the amplitude, in $\[0, 1]\$. + + + +### mle\_processed + +Return the post-processed MLE for the amplitude. + + + +### num\_evaluation\_qubits + +Returns the number of evaluation qubits. + + + +### num\_oracle\_queries + +Return the number of Grover oracle queries. + + + +### post\_processing + +Return a handle to the post processing function. + + + +### samples + +Return the measurement samples with their measurement probability. + + + +### samples\_processed + +Return the post-processed measurement samples with their measurement probability. + + + +### shots + +Return the number of shots used. Is 1 for statevector-based simulations. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimator.md b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimator.md new file mode 100644 index 00000000000..821c503ac49 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimator.md @@ -0,0 +1,36 @@ +--- +title: AmplitudeEstimator +description: API reference for qiskit.algorithms.AmplitudeEstimator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AmplitudeEstimator +--- + +# AmplitudeEstimator + + + +`qiskit.algorithms.AmplitudeEstimator`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/amplitude_estimator.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +The Amplitude Estimation interface. + +## Methods + +### estimate + + + +`abstract estimate(estimation_problem)` + +Run the amplitude estimation algorithm. + +**Parameters** + +**estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – An `EstimationProblem` containing all problem-relevant information such as the state preparation and the objective qubits. + +**Return type** + +[*AmplitudeEstimatorResult*](qiskit.algorithms.AmplitudeEstimatorResult "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimatorResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimatorResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimatorResult.md new file mode 100644 index 00000000000..5a0c1c7ded8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.AmplitudeEstimatorResult.md @@ -0,0 +1,82 @@ +--- +title: AmplitudeEstimatorResult +description: API reference for qiskit.algorithms.AmplitudeEstimatorResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.AmplitudeEstimatorResult +--- + +# AmplitudeEstimatorResult + + + +`qiskit.algorithms.AmplitudeEstimatorResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/amplitude_estimator.py "view source code") + +Bases: `AlgorithmResult` + +The results object for amplitude estimation algorithms. + +## Attributes + + + +### circuit\_results + +Return the circuit results. Can be a statevector or counts dictionary. + + + +### confidence\_interval + +Return the confidence interval for the amplitude (95% interval by default). + + + +### confidence\_interval\_processed + +Return the post-processed confidence interval (95% interval by default). + + + +### estimation + +Return the estimation for the amplitude in $[0, 1]$. + + + +### estimation\_processed + +Return the estimation for the amplitude after the post-processing has been applied. + + + +### num\_oracle\_queries + +Return the number of Grover oracle queries. + + + +### post\_processing + +Return a handle to the post processing function. + + + +### shots + +Return the number of shots used. Is 1 for statevector-based simulations. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.Eigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.Eigensolver.md new file mode 100644 index 00000000000..ad57568cab0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.Eigensolver.md @@ -0,0 +1,65 @@ +--- +title: Eigensolver +description: API reference for qiskit.algorithms.Eigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.Eigensolver +--- + +# Eigensolver + + + +`qiskit.algorithms.Eigensolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigen_solvers/eigen_solver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: Eigensolver Interface. + +The Eigensolver interface has been superseded by the [`qiskit.algorithms.eigensolvers.Eigensolver`](qiskit.algorithms.eigensolvers.Eigensolver "qiskit.algorithms.eigensolvers.Eigensolver") interface. This interface will be deprecated in a future release and subsequently removed after that. + +Algorithms that can compute eigenvalues for an operator may implement this interface to allow different algorithms to be used interchangeably. + + + The class `qiskit.algorithms.eigen_solvers.eigen_solver.Eigensolver` is deprecated as of qiskit 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the interface `qiskit.algorithms.eigensolvers.Eigensolver`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Methods + +### compute\_eigenvalues + + + +`abstract compute_eigenvalues(operator, aux_operators=None)` + +Computes eigenvalues. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +EigensolverResult + +**Return type** + +[EigensolverResult](qiskit.algorithms.EigensolverResult "qiskit.algorithms.EigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.EigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.EigensolverResult.md new file mode 100644 index 00000000000..03e7cb8b914 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.EigensolverResult.md @@ -0,0 +1,60 @@ +--- +title: EigensolverResult +description: API reference for qiskit.algorithms.EigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.EigensolverResult +--- + +# EigensolverResult + + + +`qiskit.algorithms.EigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigen_solvers/eigen_solver.py "view source code") + +Bases: `AlgorithmResult` + +Deprecated: Eigensolver Result. + +The EigensolverResult class has been superseded by the [`qiskit.algorithms.eigensolvers.EigensolverResult`](qiskit.algorithms.eigensolvers.EigensolverResult "qiskit.algorithms.eigensolvers.EigensolverResult") class. This class will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.eigen_solvers.eigen_solver.EigensolverResult` is deprecated as of qiskit 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.eigensolvers.EigensolverResult`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Attributes + + + +### aux\_operator\_eigenvalues + +Return aux operator expectation values. + +These values are in fact tuples formatted as (mean, standard deviation). + + + +### eigenstates + +return eigen states + + + +### eigenvalues + +returns eigen values + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.EstimationProblem.md b/docs/api/qiskit/0.46/qiskit.algorithms.EstimationProblem.md new file mode 100644 index 00000000000..aeac7da70d1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.EstimationProblem.md @@ -0,0 +1,116 @@ +--- +title: EstimationProblem +description: API reference for qiskit.algorithms.EstimationProblem +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.EstimationProblem +--- + +# EstimationProblem + + + +`qiskit.algorithms.EstimationProblem(state_preparation, objective_qubits, grover_operator=None, post_processing=None, is_good_state=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/estimation_problem.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +The estimation problem is the input to amplitude estimation algorithm. + +This class contains all problem-specific information required to run an amplitude estimation algorithm. That means, it minimally contains the state preparation and the specification of the good state. It can further hold some post processing on the estimation of the amplitude or a custom Grover operator. + +**Parameters** + +* **state\_preparation** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A circuit preparing the input state, referred to as $\mathcal{A}$. +* **objective\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A single qubit index or a list of qubit indices to specify which qubits to measure. The `is_good_state` function is applied on the bitstring of these objective qubits. +* **grover\_operator** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – The Grover operator $\mathcal{Q}$ used as unitary in the phase estimation circuit. +* **post\_processing** (*Callable\[\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A mapping applied to the result of the algorithm $0 \leq a \leq 1$, usually used to map the estimate to a target interval. Defaults to the identity. +* **is\_good\_state** (*Callable\[\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*],* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*] | None*) – A function to check whether a string represents a good state. Defaults to all objective qubits being in state $|1\rangle$. + +## Attributes + + + +### grover\_operator + +Get the $\mathcal{Q}$ operator, or Grover operator. + +If the Grover operator is not set, we try to build it from the $\mathcal{A}$ operator and objective\_qubits. This only works if objective\_qubits is a list of integers. + +**Returns** + +The Grover operator, or None if neither the Grover operator nor the $\mathcal{A}$ operator is set. + + + +### has\_good\_state + +Check whether an [`is_good_state`](#qiskit.algorithms.EstimationProblem.is_good_state "qiskit.algorithms.EstimationProblem.is_good_state") function is set. + +Some amplitude estimators, such as [`AmplitudeEstimation`](qiskit.algorithms.AmplitudeEstimation "qiskit.algorithms.AmplitudeEstimation") do not support a custom implementation of the [`is_good_state`](#qiskit.algorithms.EstimationProblem.is_good_state "qiskit.algorithms.EstimationProblem.is_good_state") function, and can only handle the default. + +**Returns** + +`True`, if a custom [`is_good_state`](#qiskit.algorithms.EstimationProblem.is_good_state "qiskit.algorithms.EstimationProblem.is_good_state") is set, otherwise returns `False`. + + + +### is\_good\_state + +Checks whether a bitstring represents a good state. + +**Returns** + +Handle to the `is_good_state` callable. + + + +### objective\_qubits + +Get the criterion for a measurement outcome to be in a ‘good’ state. + +**Returns** + +The criterion as list of qubit indices. + + + +### post\_processing + +Apply post processing to the input value. + +**Returns** + +A handle to the post processing function. Acts as identity by default. + + + +### state\_preparation + +Get the $\mathcal{A}$ operator encoding the amplitude $a$. + +**Returns** + +The $\mathcal{A}$ operator as QuantumCircuit. + +## Methods + +### rescale + + + +`rescale(scaling_factor)` + +Rescale the good state amplitude in the estimation problem. + +**Parameters** + +**scaling\_factor** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The scaling factor in \[0, 1]. + +**Returns** + +A rescaled estimation problem. + +**Return type** + +[*EstimationProblem*](#qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.EvolutionProblem.md b/docs/api/qiskit/0.46/qiskit.algorithms.EvolutionProblem.md new file mode 100644 index 00000000000..64be4821117 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.EvolutionProblem.md @@ -0,0 +1,62 @@ +--- +title: EvolutionProblem +description: API reference for qiskit.algorithms.EvolutionProblem +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.EvolutionProblem +--- + +# EvolutionProblem + + + +`qiskit.algorithms.EvolutionProblem(hamiltonian, time, initial_state=None, aux_operators=None, truncation_threshold=1e-12, t_param=None, param_value_dict=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/evolvers/evolution_problem.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: Evolution problem class. + +The EvolutionProblem class has been superseded by the `qiskit.algorithms.time_evolvers.TimeEvolutionProblem` class. This class will be deprecated in a future release and subsequently removed after that. + +This class is the input to time evolution algorithms and must contain information on the total evolution time, a quantum state to be evolved and under which Hamiltonian the state is evolved. + + + The class `qiskit.algorithms.evolvers.evolution_problem.EvolutionProblem` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.time_evolvers.TimeEvolutionProblem`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **hamiltonian** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – The Hamiltonian under which to evolve the system. +* **time** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Total time of evolution. +* **initial\_state** ([*StateFn*](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.StateFn") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – The quantum state to be evolved for methods like Trotterization. For variational time evolutions, where the evolution happens in an ansatz, this argument is not required. +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the evolved `initial_state` and their expectation values returned. +* **truncation\_threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Defines a threshold under which values can be assumed to be 0. Used when `aux_operators` is provided. +* **t\_param** ([*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter") *| None*) – Time parameter in case of a time-dependent Hamiltonian. This free parameter must be within the `hamiltonian`. +* **param\_value\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] | None*) – Maps free parameters in the problem to values. Depending on the algorithm, it might refer to e.g. a Hamiltonian or an initial state. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If non-positive time of evolution is provided. + +## Attributes + + + +### time + +Returns time. + +## Methods + +### validate\_params + + + +`validate_params()` + +Checks if all parameters present in the Hamiltonian are also present in the dictionary that maps them to values. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If Hamiltonian parameters cannot be bound with data provided. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.EvolutionResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.EvolutionResult.md new file mode 100644 index 00000000000..09ed5d3cd01 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.EvolutionResult.md @@ -0,0 +1,43 @@ +--- +title: EvolutionResult +description: API reference for qiskit.algorithms.EvolutionResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.EvolutionResult +--- + +# EvolutionResult + + + +`qiskit.algorithms.EvolutionResult(evolved_state, aux_ops_evaluated=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/evolvers/evolution_result.py "view source code") + +Bases: `AlgorithmResult` + +Deprecated: Class for holding evolution result. + +The EvolutionResult class has been superseded by the `qiskit.algorithms.time_evolvers.TimeEvolutionResult` class. This class will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.evolvers.evolution_result.EvolutionResult` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.time_evolvers.TimeEvolutionResult`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **evolved\_state** ([*StateFn*](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.StateFn") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – An evolved quantum state. +* **aux\_ops\_evaluated** (*ListOrDict\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]] | None*) – Optional list of observables for which expected values on an evolved state are calculated. These values are in fact tuples formatted as (mean, standard deviation). + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimation.md new file mode 100644 index 00000000000..f05209412d3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimation.md @@ -0,0 +1,129 @@ +--- +title: FasterAmplitudeEstimation +description: API reference for qiskit.algorithms.FasterAmplitudeEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.FasterAmplitudeEstimation +--- + +# FasterAmplitudeEstimation + + + +`qiskit.algorithms.FasterAmplitudeEstimation(delta, maxiter, rescale=True, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/fae.py "view source code") + +Bases: [`AmplitudeEstimator`](qiskit.algorithms.AmplitudeEstimator "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimator") + +The Faster Amplitude Estimation algorithm. + +The Faster Amplitude Estimation (FAE) \[1] algorithm is a variant of Quantum Amplitude Estimation (QAE), where the Quantum Phase Estimation (QPE) by an iterative Grover search, similar to \[2]. + +Due to the iterative version of the QPE, this algorithm does not require any additional qubits, as the originally proposed QAE \[3] and thus the resulting circuits are less complex. + +**References** + +**\[1]: K. Nakaji. Faster Amplitude Estimation, 2020;** + +[arXiv:2002.02417](https://arxiv.org/pdf/2003.02417.pdf) + +**\[2]: D. Grinko et al. Iterative Amplitude Estimation, 2019;** + +[arXiv:1912.05559](http://arxiv.org/abs/1912.05559) + +**\[3]: G. Brassard et al. Quantum Amplitude Amplification and Estimation, 2000;** + +[arXiv:quant-ph/0005055](http://arxiv.org/abs/quant-ph/0005055) + + + `qiskit.algorithms.amplitude_estimators.fae.FasterAmplitudeEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **delta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The probability that the true value is outside of the final confidence interval. +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of iterations, the maximal power of Q is 2 \*\* (maxiter - 1). +* **rescale** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to rescale the problem passed to estimate. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: The quantum instance or backend to run the circuits. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – A sampler primitive to evaluate the circuits. + + + This algorithm overwrites the number of shots set in the `quantum_instance` argument, but will reset them to the initial number after running. + + +## Attributes + + + +### quantum\_instance + +Deprecated. Get the quantum instance. + + + The property `qiskit.algorithms.amplitude_estimators.fae.FasterAmplitudeEstimation.quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Returns** + +The quantum instance used to run this algorithm. + + + +### sampler + +Get the sampler primitive. + +**Returns** + +The sampler primitive to evaluate the circuits. + +## Methods + +### construct\_circuit + + + +`construct_circuit(estimation_problem, k, measurement=False)` + +Construct the circuit $Q^k X |0\rangle>$. + +The A operator is the unitary specifying the QAE problem and Q the associated Grover operator. + +**Parameters** + +* **estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.EstimationProblem")) – The estimation problem for which to construct the circuit. +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The power of the Q operator. +* **measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Boolean flag to indicate if measurements should be included in the circuits. + +**Returns** + +The circuit $Q^k X |0\rangle$. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] + +### estimate + + + +`estimate(estimation_problem)` + +Run the amplitude estimation algorithm on provided estimation problem. + +**Parameters** + +**estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem. + +**Returns** + +An amplitude estimation results object. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – A quantum instance or Sampler must be provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – Sampler run error. + +**Return type** + +[*FasterAmplitudeEstimationResult*](qiskit.algorithms.FasterAmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.fae.FasterAmplitudeEstimationResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimationResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimationResult.md new file mode 100644 index 00000000000..4dbb1d7c8d1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.FasterAmplitudeEstimationResult.md @@ -0,0 +1,106 @@ +--- +title: FasterAmplitudeEstimationResult +description: API reference for qiskit.algorithms.FasterAmplitudeEstimationResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.FasterAmplitudeEstimationResult +--- + +# FasterAmplitudeEstimationResult + + + +`qiskit.algorithms.FasterAmplitudeEstimationResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/fae.py "view source code") + +Bases: [`AmplitudeEstimatorResult`](qiskit.algorithms.AmplitudeEstimatorResult "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimatorResult") + +The result object for the Faster Amplitude Estimation algorithm. + +## Attributes + + + +### circuit\_results + +Return the circuit results. Can be a statevector or counts dictionary. + + + +### confidence\_interval + +Return the confidence interval for the amplitude (95% interval by default). + + + +### confidence\_interval\_processed + +Return the post-processed confidence interval (95% interval by default). + + + +### estimation + +Return the estimation for the amplitude in $[0, 1]$. + + + +### estimation\_processed + +Return the estimation for the amplitude after the post-processing has been applied. + + + +### num\_first\_state\_steps + +Return the number of steps taken in the first step of algorithm. + + + +### num\_oracle\_queries + +Return the number of Grover oracle queries. + + + +### num\_steps + +Return the total number of steps taken in the algorithm. + + + +### post\_processing + +Return a handle to the post processing function. + + + +### shots + +Return the number of shots used. Is 1 for statevector-based simulations. + + + +### success\_probability + +Return the success probability of the algorithm. + + + +### theta\_intervals + +Return the confidence intervals for the angles in each iteration. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.Grover.md b/docs/api/qiskit/0.46/qiskit.algorithms.Grover.md new file mode 100644 index 00000000000..b7db25ad874 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.Grover.md @@ -0,0 +1,196 @@ +--- +title: Grover +description: API reference for qiskit.algorithms.Grover +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.Grover +--- + +# Grover + + + +`qiskit.algorithms.Grover(iterations=None, growth_rate=None, sample_from_iterations=False, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_amplifiers/grover.py "view source code") + +Bases: [`AmplitudeAmplifier`](qiskit.algorithms.AmplitudeAmplifier "qiskit.algorithms.amplitude_amplifiers.amplitude_amplifier.AmplitudeAmplifier") + +Grover’s Search algorithm. + + + If you want to learn more about the theory behind Grover’s Search algorithm, check out the [Qiskit Textbook](https://qiskit.org/textbook/ch-algorithms/grover.html). or the [Qiskit Tutorials](https://qiskit.org/documentation/tutorials/algorithms/07_grover_examples.html) for more concrete how-to examples. + + +Grover’s Search \[1, 2] is a well known quantum algorithm that can be used for searching through unstructured collections of records for particular targets with quadratic speedup compared to classical algorithms. + +Given a set $X$ of $N$ elements $X=\{x_1,x_2,\ldots,x_N\}$ and a boolean function $f : X \rightarrow \{0,1\}$, the goal of an unstructured-search problem is to find an element $x^* \in X$ such that $f(x^*)=1$. + +The search is called *unstructured* because there are no guarantees as to how the database is ordered. On a sorted database, for instance, one could perform binary search to find an element in $\mathbb{O}(\log N)$ worst-case time. Instead, in an unstructured-search problem, there is no prior knowledge about the contents of the database. With classical circuits, there is no alternative but to perform a linear number of queries to find the target element. Conversely, Grover’s Search algorithm allows to solve the unstructured-search problem on a quantum computer in $\mathcal{O}(\sqrt{N})$ queries. + +To carry out this search a so-called oracle is required, that flags a good element/state. The action of the oracle $\mathcal{S}_f$ is + +$$ +\mathcal{S}_f |x\rangle = (-1)^{f(x)} |x\rangle, +$$ + +i.e. it flips the phase of the state $|x\rangle$ if $x$ is a hit. The details of how $S_f$ works are unimportant to the algorithm; Grover’s search algorithm treats the oracle as a black box. + +This class supports oracles in form of a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +With the given oracle, Grover’s Search constructs the Grover operator to amplify the amplitudes of the good states: + +$$ +\mathcal{Q} = H^{\otimes n} \mathcal{S}_0 H^{\otimes n} \mathcal{S}_f + = D \mathcal{S}_f, +$$ + +where $\mathcal{S}_0$ flips the phase of the all-zero state and acts as identity on all other states. Sometimes the first three operands are summarized as diffusion operator, which implements a reflection over the equal superposition state. + +If the number of solutions is known, we can calculate how often $\mathcal{Q}$ should be applied to find a solution with very high probability, see the method optimal\_num\_iterations. If the number of solutions is unknown, the algorithm tries different powers of Grover’s operator, see the iterations argument, and after each iteration checks if a good state has been measured using good\_state. + +The generalization of Grover’s Search, Quantum Amplitude Amplification \[3], uses a modified version of $\mathcal{Q}$ where the diffusion operator does not reflect about the equal superposition state, but another state specified via an operator $\mathcal{A}$: + +$$ +\mathcal{Q} = \mathcal{A} \mathcal{S}_0 \mathcal{A}^\dagger \mathcal{S}_f. +$$ + +For more information, see the [`GroverOperator`](qiskit.circuit.library.GroverOperator "qiskit.circuit.library.GroverOperator") in the circuit library. + +**References** + +**\[1]: L. K. Grover (1996), A fast quantum mechanical algorithm for database search,** + +[arXiv:quant-ph/9605043](https://arxiv.org/abs/quant-ph/9605043). + +**\[2]: I. Chuang & M. Nielsen, Quantum Computation and Quantum Information,** + +Cambridge: Cambridge University Press, 2000. Chapter 6.1.2. + +**\[3]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000).** + +Quantum Amplitude Amplification and Estimation. [arXiv:quant-ph/0005055](http://arxiv.org/abs/quant-ph/0005055). + + + `qiskit.algorithms.amplitude_amplifiers.grover.Grover.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **iterations** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | Iterator\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Specify the number of iterations/power of Grover’s operator to be checked. \* If an int, only one circuit is run with that power of the Grover operator. If the number of solutions is known, this option should be used with the optimal power. The optimal power can be computed with `Grover.optimal_num_iterations`. \* If a list, all the powers in the list are run in the specified order. \* If an iterator, the powers yielded by the iterator are checked, until a maximum number of iterations or maximum power is reached. \* If `None`, the [`AmplificationProblem`](qiskit.algorithms.AmplificationProblem "qiskit.algorithms.AmplificationProblem") provided must have an `is_good_state`, and circuits are run until that good state is reached. +* **growth\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – If specified, the iterator is set to increasing powers of `growth_rate`, i.e. to `int(growth_rate ** 1), int(growth_rate ** 2), ...` until a maximum number of iterations is reached. +* **sample\_from\_iterations** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, instead of taking the values in `iterations` as powers of the Grover operator, a random integer sample between 0 and smaller value than the iteration is used as a power, see \[1], Section 4. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: A Quantum Instance or Backend to run the circuits. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – A Sampler to use for sampling the results of the circuits. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `growth_rate` is a float but not larger than 1. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If both `iterations` and `growth_rate` is set. + +**References** + +**\[1]: Boyer et al., Tight bounds on quantum searching** + +[https://arxiv.org/abs/quant-ph/9605034](https://arxiv.org/abs/quant-ph/9605034) + +## Attributes + + + +### quantum\_instance + +Deprecated. Get the quantum instance. + + + The property `qiskit.algorithms.amplitude_amplifiers.grover.Grover.quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Returns** + +The quantum instance used to run this algorithm. + + + +### sampler + +Get the sampler. + +**Returns** + +The sampler used to run this algorithm. + +## Methods + +### amplify + + + +`amplify(amplification_problem)` + +Run the Grover algorithm. + +**Parameters** + +**amplification\_problem** ([*AmplificationProblem*](qiskit.algorithms.AmplificationProblem "qiskit.algorithms.amplitude_amplifiers.amplification_problem.AmplificationProblem")) – The amplification problem. + +**Returns** + +The result as a `GroverResult`, where e.g. the most likely state can be queried as `result.top_measurement`. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If a quantum instance or sampler is not set. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If a sampler job fails. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `is_good_state` is not provided and is required (i.e. when iterations +* **is None**\*\* or ****a list****)\*\* – + +**Return type** + +[*GroverResult*](qiskit.algorithms.GroverResult "qiskit.algorithms.amplitude_amplifiers.grover.GroverResult") + +### construct\_circuit + + + +`construct_circuit(problem, power=None, measurement=False)` + +Construct the circuit for Grover’s algorithm with `power` Grover operators. + +**Parameters** + +* **problem** ([*AmplificationProblem*](qiskit.algorithms.AmplificationProblem "qiskit.algorithms.AmplificationProblem")) – The amplification problem for the algorithm. +* **power** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of times the Grover operator is repeated. If None, this argument is set to the first item in `iterations`. +* **measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Boolean flag to indicate if measurement should be included in the circuit. + +**Returns** + +the QuantumCircuit object for the constructed circuit + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If no power is passed and the iterations are not an integer. + +### optimal\_num\_iterations + + + +`static optimal_num_iterations(num_solutions, num_qubits)` + +Return the optimal number of iterations, if the number of solutions is known. + +**Parameters** + +* **num\_solutions** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of solutions. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits used to encode the states. + +**Returns** + +The optimal number of iterations for Grover’s algorithm to succeed. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.GroverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.GroverResult.md new file mode 100644 index 00000000000..2c282eeee73 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.GroverResult.md @@ -0,0 +1,86 @@ +--- +title: GroverResult +description: API reference for qiskit.algorithms.GroverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.GroverResult +--- + +# GroverResult + + + +`qiskit.algorithms.GroverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_amplifiers/grover.py "view source code") + +Bases: `AmplitudeAmplifierResult` + +Grover Result. + +## Attributes + + + +### assignment + +The post-processed value of the most likely bitstring. + +**Returns** + +The output of the `post_processing` function of the respective `AmplificationProblem`, where the input is the `top_measurement`. The type is the same as the return type of the post-processing function. + + + +### circuit\_results + +Return the circuit results. Can be a statevector or counts dictionary. + + + +### iterations + +All the powers of the Grover operator that have been tried. + +**Returns** + +The powers of the Grover operator tested. + + + +### max\_probability + +Return the maximum sampling probability. + + + +### oracle\_evaluation + +Whether the classical oracle evaluation of the top measurement was True or False. + +**Returns** + +The classical oracle evaluation of the top measurement. + + + +### top\_measurement + +The most frequently measured output as bitstring. + +**Returns** + +The most frequently measured output state. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimation.md new file mode 100644 index 00000000000..17276958a9c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimation.md @@ -0,0 +1,90 @@ +--- +title: HamiltonianPhaseEstimation +description: API reference for qiskit.algorithms.HamiltonianPhaseEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.HamiltonianPhaseEstimation +--- + +# HamiltonianPhaseEstimation + + + +`qiskit.algorithms.HamiltonianPhaseEstimation(num_evaluation_qubits, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/phase_estimators/hamiltonian_phase_estimation.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Run the Quantum Phase Estimation algorithm to find the eigenvalues of a Hermitian operator. + +This class is nearly the same as [`PhaseEstimation`](qiskit.algorithms.PhaseEstimation "qiskit.algorithms.PhaseEstimation"), differing only in that the input in that class is a unitary operator, whereas here the input is a Hermitian operator from which a unitary will be obtained by scaling and exponentiating. The scaling is performed in order to prevent the phases from wrapping around $2\pi$. The problem of estimating eigenvalues $\lambda_j$ of the Hermitian operator $H$ is solved by running a circuit representing + +$$ +\exp(i b H) |\psi\rangle = \sum_j \exp(i b \lambda_j) c_j |\lambda_j\rangle, +$$ + +where the input state is + +$$ +|\psi\rangle = \sum_j c_j |\lambda_j\rangle, +$$ + +and $\lambda_j$ are the eigenvalues of $H$. + +Here, $b$ is a scaling factor sufficiently large to map positive $\lambda$ to $[0,\pi)$ and negative $\lambda$ to $[\pi,2\pi)$. Each time the circuit is run, one measures a phase corresponding to $lambda_j$ with probability $|c_j|^2$. + +If $H$ is a Pauli sum, the bound $b$ is computed from the sum of the absolute values of the coefficients of the terms. There is no way to reliably recover eigenvalues from phases very near the endpoints of these intervals. Because of this you should be aware that for degenerate cases, such as $H=Z$, the eigenvalues $\pm 1$ will be mapped to the same phase, $\pi$, and so cannot be distinguished. In this case, you need to specify a larger bound as an argument to the method `estimate`. + +This class uses and works together with [`PhaseEstimationScale`](qiskit.algorithms.PhaseEstimationScale "qiskit.algorithms.PhaseEstimationScale") to manage scaling the Hamiltonian and the phases that are obtained by the QPE algorithm. This includes setting, or computing, a bound on the eigenvalues of the operator, using this bound to obtain a scale factor, scaling the operator, and shifting and scaling the measured phases to recover the eigenvalues. + +Note that, although we speak of “evolving” the state according the Hamiltonian, in the present algorithm, we are not actually considering time evolution. Rather, the role of time is played by the scaling factor, which is chosen to best extract the eigenvalues of the Hamiltonian. + +A few of the ideas in the algorithm may be found in Ref. \[1]. + +**Reference:** + +**\[1]: Quantum phase estimation of multiple eigenvalues for small-scale (noisy) experiments** + +T.E. O’Brien, B. Tarasinski, B.M. Terhal [arXiv:1809.09697](https://arxiv.org/abs/1809.09697) + + + `qiskit.algorithms.phase_estimators.hamiltonian_phase_estimation.HamiltonianPhaseEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **num\_evaluation\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits used in estimating the phase. The phase will be estimated as a binary string with this many bits. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: The quantum instance on which the circuit will be run. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – The sampler primitive on which the circuit will be sampled. + +## Methods + +### estimate + + + +`estimate(hamiltonian, state_preparation=None, evolution=None, bound=None)` + +Run the Hamiltonian phase estimation algorithm. + +**Parameters** + +* **hamiltonian** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.PauliOp") *|*[*MatrixOp*](qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.MatrixOp") *|*[*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp") *|*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – A Hermitian operator. If the algorithm is used with a `Sampler` primitive, the allowed types are `Pauli`, `SparsePauliOp`, and `PauliSumOp`. If the algorithm is used with a `QuantumInstance`, `PauliOp, ``MatrixOp`, `PauliSumOp`, and `SummedOp` types are allowed. +* **state\_preparation** ([*StateFn*](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.StateFn") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *| None*) – The `StateFn` to be prepared, whose eigenphase will be measured. If this parameter is omitted, no preparation circuit will be run and input state will be the all-zero state in the computational basis. +* **evolution** ([*EvolutionSynthesis*](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis") *|*[*EvolutionBase*](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.EvolutionBase") *| None*) – An evolution converter that generates a unitary from `hamiltonian`. If `None`, then the default `PauliTrotterEvolution` is used. +* **bound** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – An upper bound on the absolute value of the eigenvalues of `hamiltonian`. If omitted, then `hamiltonian` must be a Pauli sum, or a `PauliOp`, in which case a bound will be computed. If `hamiltonian` is a `MatrixOp`, then `bound` may not be `None`. The tighter the bound, the higher the resolution of computed phases. + +**Returns** + +`HamiltonianPhaseEstimationResult` instance containing the result of the estimation and diagnostic information. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `evolution` is not of type `EvolutionSynthesis` when a `Sampler` is provided. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `hamiltonian` type is not `Pauli` or `SparsePauliOp` or `PauliSumOp` when a `Sampler` is provided. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `bound` is `None` and `hamiltonian` is not a Pauli sum, i.e. a `PauliSumOp` or a `SummedOp` whose terms are of type `PauliOp`. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `evolution` is not of type `EvolutionBase` when no `Sampler` is provided. + +**Return type** + +[HamiltonianPhaseEstimationResult](qiskit.algorithms.HamiltonianPhaseEstimationResult "qiskit.algorithms.HamiltonianPhaseEstimationResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimationResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimationResult.md new file mode 100644 index 00000000000..5b81fe777f5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.HamiltonianPhaseEstimationResult.md @@ -0,0 +1,92 @@ +--- +title: HamiltonianPhaseEstimationResult +description: API reference for qiskit.algorithms.HamiltonianPhaseEstimationResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.HamiltonianPhaseEstimationResult +--- + +# HamiltonianPhaseEstimationResult + + + +`qiskit.algorithms.HamiltonianPhaseEstimationResult(phase_estimation_result, phase_estimation_scale, id_coefficient)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/phase_estimators/hamiltonian_phase_estimation_result.py "view source code") + +Bases: `AlgorithmResult` + +Store and manipulate results from running HamiltonianPhaseEstimation. + +This API of this class is nearly the same as PhaseEstimatorResult, differing only in the presence of an additional keyword argument in the methods. If scaled is False, then the phases are not translated and scaled to recover the eigenvalues of the Hamiltonian. Instead phi in $[0, 1)$ is returned, as is the case when then unitary is not derived from a Hamiltonian. + +This class is meant to be instantiated via HamiltonianPhaseEstimation.estimate. + +**Parameters** + +* **phase\_estimation\_result** ([*PhaseEstimationResult*](qiskit.algorithms.PhaseEstimationResult "qiskit.algorithms.PhaseEstimationResult")) – The result object returned by PhaseEstimation.estimate. +* **phase\_estimation\_scale** ([*PhaseEstimationScale*](qiskit.algorithms.PhaseEstimationScale "qiskit.algorithms.PhaseEstimationScale")) – object used to scale phases to obtain eigenvalues. +* **id\_coefficient** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The coefficient of the identity term in the Hamiltonian. Eigenvalues are computed without this term so that the coefficient must added to give correct eigenvalues. This is done automatically when retrieving eigenvalues. + +## Attributes + + + +### most\_likely\_eigenvalue + +The most likely eigenvalue of the Hamiltonian. + +This method calls most\_likely\_phase and scales the result to obtain an eigenvalue. + +**Returns** + +The most likely eigenvalue of the Hamiltonian. + + + +### phase + +The most likely phase of the unitary corresponding to the Hamiltonian. + +**Returns** + +The most likely phase. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + +### filter\_phases + + + +`filter_phases(cutoff=0.0, scaled=True, as_float=True)` + +Filter phases as does PhaseEstimatorResult.filter\_phases, with the addition that phi is shifted and translated to return eigenvalues of the Hamiltonian. + +**Parameters** + +* **cutoff** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Minimum weight of number of counts required to keep a bit string. The default value is 0.0. +* **scaled** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If False, return phi in $[0, 1)$ rather than the eigenvalues of the Hamiltonian. +* **as\_float** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, returned keys are floats in $[0.0, 1.0)$. If False returned keys are bit strings. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if as\_float is False and scaled is True. + +**Returns** + +A dict of filtered phases. + +**Return type** + +Mapping\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryEvolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryEvolver.md new file mode 100644 index 00000000000..27922a3abc0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryEvolver.md @@ -0,0 +1,48 @@ +--- +title: ImaginaryEvolver +description: API reference for qiskit.algorithms.ImaginaryEvolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.ImaginaryEvolver +--- + +# ImaginaryEvolver + + + +`qiskit.algorithms.ImaginaryEvolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/evolvers/imaginary_evolver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: Interface for Quantum Imaginary Time Evolution. + +The ImaginaryEvolver interface has been superseded by the `qiskit.algorithms.time_evolvers.ImaginaryTimeEvolver` interface. This interface will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.evolvers.imaginary_evolver.ImaginaryEvolver` is deprecated as of qiskit 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the interface `qiskit.algorithms.time_evolvers.ImaginaryTimeEvolver`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Methods + +### evolve + + + +`abstract evolve(evolution_problem)` + +Perform imaginary time evolution $\exp(-\tau H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for an imaginary time $\tau$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*EvolutionProblem*](qiskit.algorithms.EvolutionProblem "qiskit.algorithms.evolvers.evolution_problem.EvolutionProblem")) – The definition of the evolution problem. + +**Returns** + +Evolution result which includes an evolved quantum state. + +**Return type** + +[*EvolutionResult*](qiskit.algorithms.EvolutionResult "qiskit.algorithms.evolvers.evolution_result.EvolutionResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryTimeEvolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryTimeEvolver.md new file mode 100644 index 00000000000..d69a3a74c68 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.ImaginaryTimeEvolver.md @@ -0,0 +1,42 @@ +--- +title: ImaginaryTimeEvolver +description: API reference for qiskit.algorithms.ImaginaryTimeEvolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.ImaginaryTimeEvolver +--- + +# ImaginaryTimeEvolver + + + +`qiskit.algorithms.ImaginaryTimeEvolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/imaginary_time_evolver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Interface for Quantum Imaginary Time Evolution. + +## Methods + +### evolve + + + +`abstract evolve(evolution_problem)` + +Perform imaginary time evolution $\exp(-\tau H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for an imaginary time $\tau$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – The definition of the evolution problem. + +**Returns** + +Evolution result which includes an evolved quantum state. + +**Return type** + +[*TimeEvolutionResult*](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimation.md new file mode 100644 index 00000000000..6469f0cf473 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimation.md @@ -0,0 +1,141 @@ +--- +title: IterativeAmplitudeEstimation +description: API reference for qiskit.algorithms.IterativeAmplitudeEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.IterativeAmplitudeEstimation +--- + +# IterativeAmplitudeEstimation + + + +`qiskit.algorithms.IterativeAmplitudeEstimation(epsilon_target, alpha, confint_method='beta', min_ratio=2, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/iae.py "view source code") + +Bases: [`AmplitudeEstimator`](qiskit.algorithms.AmplitudeEstimator "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimator") + +The Iterative Amplitude Estimation algorithm. + +This class implements the Iterative Quantum Amplitude Estimation (IQAE) algorithm, proposed in \[1]. The output of the algorithm is an estimate that, with at least probability $1 - \alpha$, differs by epsilon to the target value, where both alpha and epsilon can be specified. + +It differs from the original QAE algorithm proposed by Brassard \[2] in that it does not rely on Quantum Phase Estimation, but is only based on Grover’s algorithm. IQAE iteratively applies carefully selected Grover iterations to find an estimate for the target amplitude. + +**References** + +**\[1]: Grinko, D., Gacon, J., Zoufal, C., & Woerner, S. (2019).** + +Iterative Quantum Amplitude Estimation. [arXiv:1912.05559](https://arxiv.org/abs/1912.05559). + +**\[2]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000).** + +Quantum Amplitude Amplification and Estimation. [arXiv:quant-ph/0005055](http://arxiv.org/abs/quant-ph/0005055). + +The output of the algorithm is an estimate for the amplitude a, that with at least probability 1 - alpha has an error of epsilon. The number of A operator calls scales linearly in 1/epsilon (up to a logarithmic factor). + + + `qiskit.algorithms.amplitude_estimators.iae.IterativeAmplitudeEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **epsilon\_target** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Target precision for estimation target a, has values between 0 and 0.5 +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Confidence level, the target probability is 1 - alpha, has values between 0 and 1 +* **confint\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Statistical method used to estimate the confidence intervals in each iteration, can be ‘chernoff’ for the Chernoff intervals or ‘beta’ for the Clopper-Pearson intervals (default) +* **min\_ratio** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Minimal q-ratio ($K_{i+1} / K_i$) for FindNextK +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: Quantum Instance or Backend +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – A sampler primitive to evaluate the circuits. + +**Raises** + +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – if the method to compute the confidence intervals is not supported +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the target epsilon is not in (0, 0.5] +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If alpha is not in (0, 1) +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If confint\_method is not supported + +## Attributes + + + +### epsilon\_target + +Returns the target precision `epsilon_target` of the algorithm. + +**Returns** + +The target precision (which is half the width of the confidence interval). + + + +### quantum\_instance + +Deprecated. Get the quantum instance. + + + The property `qiskit.algorithms.amplitude_estimators.iae.IterativeAmplitudeEstimation.quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Returns** + +The quantum instance used to run this algorithm. + + + +### sampler + +Get the sampler primitive. + +**Returns** + +The sampler primitive to evaluate the circuits. + +## Methods + +### construct\_circuit + + + +`construct_circuit(estimation_problem, k=0, measurement=False)` + +Construct the circuit $\mathcal{Q}^k \mathcal{A} |0\rangle$. + +The A operator is the unitary specifying the QAE problem and Q the associated Grover operator. + +**Parameters** + +* **estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem for which to construct the QAE circuit. +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The power of the Q operator. +* **measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Boolean flag to indicate if measurements should be included in the circuits. + +**Returns** + +The circuit implementing $\mathcal{Q}^k \mathcal{A} |0\rangle$. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### estimate + + + +`estimate(estimation_problem)` + +Run the amplitude estimation algorithm on provided estimation problem. + +**Parameters** + +**estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem. + +**Returns** + +An amplitude estimation results object. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – A quantum instance or Sampler must be provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – Sampler job run error. + +**Return type** + +[*IterativeAmplitudeEstimationResult*](qiskit.algorithms.IterativeAmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.iae.IterativeAmplitudeEstimationResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimationResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimationResult.md new file mode 100644 index 00000000000..a15dbdf6a71 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.IterativeAmplitudeEstimationResult.md @@ -0,0 +1,130 @@ +--- +title: IterativeAmplitudeEstimationResult +description: API reference for qiskit.algorithms.IterativeAmplitudeEstimationResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.IterativeAmplitudeEstimationResult +--- + +# IterativeAmplitudeEstimationResult + + + +`qiskit.algorithms.IterativeAmplitudeEstimationResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/iae.py "view source code") + +Bases: [`AmplitudeEstimatorResult`](qiskit.algorithms.AmplitudeEstimatorResult "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimatorResult") + +The `IterativeAmplitudeEstimation` result object. + +## Attributes + + + +### alpha + +Return the confidence level $\alpha$. + + + +### circuit\_results + +Return the circuit results. Can be a statevector or counts dictionary. + + + +### confidence\_interval + +Return the confidence interval for the amplitude (95% interval by default). + + + +### confidence\_interval\_processed + +Return the post-processed confidence interval. + + + +### epsilon\_estimated + +Return the estimated half-width of the confidence interval. + + + +### epsilon\_estimated\_processed + +Return the post-processed estimated half-width of the confidence interval. + + + +### epsilon\_target + +Return the target half-width of the confidence interval. + + + +### estimate\_intervals + +Return the confidence intervals for the estimate in each iteration. + + + +### estimation + +Return the estimation for the amplitude in $[0, 1]$. + + + +### estimation\_processed + +Return the estimation for the amplitude after the post-processing has been applied. + + + +### num\_oracle\_queries + +Return the number of Grover oracle queries. + + + +### post\_processing + +Return a handle to the post processing function. + + + +### powers + +Return the powers of the Grover operator in each iteration. + + + +### ratios + +Return the ratios $K_{i+1}/K_{i}$ for each iteration $i$. + + + +### shots + +Return the number of shots used. Is 1 for statevector-based simulations. + + + +### theta\_intervals + +Return the confidence intervals for the angles in each iteration. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.IterativePhaseEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.IterativePhaseEstimation.md new file mode 100644 index 00000000000..3095e76d3f6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.IterativePhaseEstimation.md @@ -0,0 +1,92 @@ +--- +title: IterativePhaseEstimation +description: API reference for qiskit.algorithms.IterativePhaseEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.IterativePhaseEstimation +--- + +# IterativePhaseEstimation + + + +`qiskit.algorithms.IterativePhaseEstimation(num_iterations, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/phase_estimators/ipe.py "view source code") + +Bases: `PhaseEstimator` + +Run the Iterative quantum phase estimation (QPE) algorithm. + +Given a unitary circuit and a circuit preparing an eigenstate, return the phase of the eigenvalue as a number in $[0,1)$ using the iterative phase estimation algorithm. + +**\[1]: Dobsicek et al. (2006), Arbitrary accuracy iterative phase estimation algorithm as a two** + +qubit benchmark, [arxiv/quant-ph/0610214](https://arxiv.org/abs/quant-ph/0610214) + + + `qiskit.algorithms.phase_estimators.ipe.IterativePhaseEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **num\_iterations** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of iterations (rounds) of the phase estimation to run. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: The quantum instance on which the circuit will be run. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – The sampler primitive on which the circuit will be sampled. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if num\_iterations is not greater than zero. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If neither sampler nor quantum instance is provided. + +## Methods + +### construct\_circuit + + + +`construct_circuit(unitary, state_preparation, k, omega=0.0, measurement=False)` + +Construct the kth iteration Quantum Phase Estimation circuit. + +For details of parameters, see Fig. 2 in [https://arxiv.org/pdf/quant-ph/0610214.pdf](https://arxiv.org/pdf/quant-ph/0610214.pdf). + +**Parameters** + +* **unitary** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The circuit representing the unitary operator whose eigenvalue (via phase) will be measured. +* **state\_preparation** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The circuit that prepares the state whose eigenphase will be measured. If this parameter is omitted, no preparation circuit will be run and input state will be the all-zero state in the computational basis. +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the iteration idx. +* **omega** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the feedback angle. +* **measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Boolean flag to indicate if measurement should be included in the circuit. + +**Returns** + +the quantum circuit per iteration + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### estimate + + + +`estimate(unitary, state_preparation)` + +Estimate the eigenphase of the input unitary and initial-state pair. + +**Parameters** + +* **unitary** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The circuit representing the unitary operator whose eigenvalue (via phase) will be measured. +* **state\_preparation** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The circuit that prepares the state whose eigenphase will be measured. If this parameter is omitted, no preparation circuit will be run and input state will be the all-zero state in the computational basis. + +**Returns** + +Estimated phase in an IterativePhaseEstimationResult object. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If neither sampler nor quantum instance is provided. + +**Return type** + +*IterativePhaseEstimationResult* + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation.md new file mode 100644 index 00000000000..a3678f12946 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation.md @@ -0,0 +1,175 @@ +--- +title: MaximumLikelihoodAmplitudeEstimation +description: API reference for qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation +--- + +# MaximumLikelihoodAmplitudeEstimation + + + +`qiskit.algorithms.MaximumLikelihoodAmplitudeEstimation(evaluation_schedule, minimizer=None, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/mlae.py "view source code") + +Bases: [`AmplitudeEstimator`](qiskit.algorithms.AmplitudeEstimator "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimator") + +The Maximum Likelihood Amplitude Estimation algorithm. + +This class implements the quantum amplitude estimation (QAE) algorithm without phase estimation, as introduced in \[1]. In comparison to the original QAE algorithm \[2], this implementation relies solely on different powers of the Grover operator and does not require additional evaluation qubits. Finally, the estimate is determined via a maximum likelihood estimation, which is why this class in named `MaximumLikelihoodAmplitudeEstimation`. + +**References** + +**\[1]: Suzuki, Y., Uno, S., Raymond, R., Tanaka, T., Onodera, T., & Yamamoto, N. (2019).** + +Amplitude Estimation without Phase Estimation. [arXiv:1904.10246](https://arxiv.org/abs/1904.10246). + +**\[2]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000).** + +Quantum Amplitude Amplification and Estimation. [arXiv:quant-ph/0005055](http://arxiv.org/abs/quant-ph/0005055). + + + `qiskit.algorithms.amplitude_estimators.mlae.MaximumLikelihoodAmplitudeEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **evaluation\_schedule** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – If a list, the powers applied to the Grover operator. The list element must be non-negative. If a non-negative integer, an exponential schedule is used where the highest power is 2 to the integer minus 1: \[id, Q^2^0, …, Q^2^(evaluation\_schedule-1)]. +* **minimizer** (*MINIMIZER | None*) – A minimizer used to find the minimum of the likelihood function. Defaults to a brute search where the number of evaluation points is determined according to `evaluation_schedule`. The minimizer takes a function as first argument and a list of (float, float) tuples (as bounds) as second argument and returns a single float which is the found minimum. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: Quantum Instance or Backend +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – A sampler primitive to evaluate the circuits. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the number of oracle circuits is smaller than 1. + +## Attributes + + + +### quantum\_instance + +Deprecated. Get the quantum instance. + + + The property `qiskit.algorithms.amplitude_estimators.mlae.MaximumLikelihoodAmplitudeEstimation.quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Returns** + +The quantum instance used to run this algorithm. + + + +### sampler + +Get the sampler primitive. + +**Returns** + +The sampler primitive to evaluate the circuits. + +## Methods + +### compute\_confidence\_interval + + + +`static compute_confidence_interval(result, alpha, kind='fisher', apply_post_processing=False)` + +Compute the alpha confidence interval using the method kind. + +The confidence level is (1 - alpha) and supported kinds are ‘fisher’, ‘likelihood\_ratio’ and ‘observed\_fisher’ with shorthand notations ‘fi’, ‘lr’ and ‘oi’, respectively. + +**Parameters** + +* **result** ([*MaximumLikelihoodAmplitudeEstimationResult*](qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.mlae.MaximumLikelihoodAmplitudeEstimationResult")) – A maximum likelihood amplitude estimation result. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The confidence level. +* **kind** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The method to compute the confidence interval. Defaults to ‘fisher’, which computes the theoretical Fisher information. +* **apply\_post\_processing** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, apply post-processing to the confidence interval. + +**Returns** + +The specified confidence interval. + +**Raises** + +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If run() hasn’t been called yet. +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If the method kind is not supported. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### compute\_mle + + + +`compute_mle(circuit_results, estimation_problem, num_state_qubits=None, return_counts=False)` + +Compute the MLE via a grid-search. + +This is a stable approach if sufficient gridpoints are used. + +**Parameters** + +* **circuit\_results** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | np.ndarray]*) – A list of circuit outcomes. Can be counts or statevectors. +* **estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.EstimationProblem")) – The estimation problem containing the evaluation schedule and the number of likelihood function evaluations used to find the minimum. +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of state qubits, required for statevector simulations. +* **return\_counts** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, returns the good counts. + +**Returns** + +The MLE for the provided result object. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] + +### construct\_circuits + + + +`construct_circuits(estimation_problem, measurement=False)` + +Construct the Amplitude Estimation w/o QPE quantum circuits. + +**Parameters** + +* **estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem for which to construct the QAE circuit. +* **measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Boolean flag to indicate if measurement should be included in the circuits. + +**Returns** + +A list with the QuantumCircuit objects for the algorithm. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.circuit.quantumcircuit.QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")] + +### estimate + + + +`estimate(estimation_problem)` + +Run the amplitude estimation algorithm on provided estimation problem. + +**Parameters** + +**estimation\_problem** ([*EstimationProblem*](qiskit.algorithms.EstimationProblem "qiskit.algorithms.amplitude_estimators.estimation_problem.EstimationProblem")) – The estimation problem. + +**Returns** + +An amplitude estimation results object. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – A quantum instance or Sampler must be provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If state\_preparation is not set in estimation\_problem. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – Sampler job run error + +**Return type** + +[*MaximumLikelihoodAmplitudeEstimationResult*](qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult "qiskit.algorithms.amplitude_estimators.mlae.MaximumLikelihoodAmplitudeEstimationResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult.md new file mode 100644 index 00000000000..88a16515f26 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult.md @@ -0,0 +1,112 @@ +--- +title: MaximumLikelihoodAmplitudeEstimationResult +description: API reference for qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult +--- + +# MaximumLikelihoodAmplitudeEstimationResult + + + +`qiskit.algorithms.MaximumLikelihoodAmplitudeEstimationResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/amplitude_estimators/mlae.py "view source code") + +Bases: [`AmplitudeEstimatorResult`](qiskit.algorithms.AmplitudeEstimatorResult "qiskit.algorithms.amplitude_estimators.amplitude_estimator.AmplitudeEstimatorResult") + +The `MaximumLikelihoodAmplitudeEstimation` result object. + +## Attributes + + + +### circuit\_results + +Return the circuit results. Can be a statevector or counts dictionary. + + + +### confidence\_interval + +Return the confidence interval for the amplitude (95% interval by default). + + + +### confidence\_interval\_processed + +Return the post-processed confidence interval (95% interval by default). + + + +### estimation + +Return the estimation for the amplitude in $[0, 1]$. + + + +### estimation\_processed + +Return the estimation for the amplitude after the post-processing has been applied. + + + +### evaluation\_schedule + +Return the evaluation schedule for the powers of the Grover operator. + + + +### fisher\_information + +Return the Fisher information for the estimated amplitude. + + + +### good\_counts + +Return the percentage of good counts per circuit power. + + + +### minimizer + +Return the minimizer used for the search of the likelihood function. + + + +### num\_oracle\_queries + +Return the number of Grover oracle queries. + + + +### post\_processing + +Return a handle to the post processing function. + + + +### shots + +Return the number of shots used. Is 1 for statevector-based simulations. + + + +### theta + +Return the estimate for the angle $\theta$. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolver.md new file mode 100644 index 00000000000..9dd4b03ecfd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolver.md @@ -0,0 +1,67 @@ +--- +title: MinimumEigensolver +description: API reference for qiskit.algorithms.MinimumEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.MinimumEigensolver +--- + +# MinimumEigensolver + + + +`qiskit.algorithms.MinimumEigensolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigen_solvers/minimum_eigen_solver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: Minimum Eigensolver Interface. + +The Minimum Eigensolver interface has been superseded by the [`qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver") interface. This interface will be deprecated in a future release and subsequently removed after that. + +Algorithms that can compute a minimum eigenvalue for an operator may implement this interface to allow different algorithms to be used interchangeably. + + + The class `qiskit.algorithms.minimum_eigen_solvers.minimum_eigen_solver.MinimumEigensolver` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the interface `qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Methods + +### compute\_minimum\_eigenvalue + + + +`abstract compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes minimum eigenvalue. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +MinimumEigensolverResult + +**Return type** + +[MinimumEigensolverResult](qiskit.algorithms.MinimumEigensolverResult "qiskit.algorithms.MinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolverResult.md new file mode 100644 index 00000000000..361249940ab --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.MinimumEigensolverResult.md @@ -0,0 +1,60 @@ +--- +title: MinimumEigensolverResult +description: API reference for qiskit.algorithms.MinimumEigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.MinimumEigensolverResult +--- + +# MinimumEigensolverResult + + + +`qiskit.algorithms.MinimumEigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigen_solvers/minimum_eigen_solver.py "view source code") + +Bases: `AlgorithmResult` + +Deprecated: Minimum Eigensolver Result. + +The MinimumEigensolverResult class has been superseded by the [`qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult") class. This class will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.minimum_eigen_solvers.minimum_eigen_solver.MinimumEigensolverResult` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Attributes + + + +### aux\_operator\_eigenvalues + +Return aux operator expectation values. + +These values are in fact tuples formatted as (mean, standard deviation). + + + +### eigenstate + +return eigen state + + + +### eigenvalue + +returns eigen value + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.NumPyEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.NumPyEigensolver.md new file mode 100644 index 00000000000..10eac4810ba --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.NumPyEigensolver.md @@ -0,0 +1,88 @@ +--- +title: NumPyEigensolver +description: API reference for qiskit.algorithms.NumPyEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.NumPyEigensolver +--- + +# NumPyEigensolver + + + +`qiskit.algorithms.NumPyEigensolver(k=1, filter_criterion=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigen_solvers/numpy_eigen_solver.py "view source code") + +Bases: [`Eigensolver`](qiskit.algorithms.Eigensolver "qiskit.algorithms.eigen_solvers.eigen_solver.Eigensolver") + +Deprecated: NumPy Eigensolver algorithm. + +The NumPyEigensolver class has been superseded by the [`qiskit.algorithms.eigensolvers.NumPyEigensolver`](qiskit.algorithms.eigensolvers.NumPyEigensolver "qiskit.algorithms.eigensolvers.NumPyEigensolver") class. This class will be deprecated in a future release and subsequently removed after that. + +NumPy Eigensolver computes up to the first $k$ eigenvalues of a complex-valued square matrix of dimension $n \times n$, with $k \leq n$. + + + Operators are automatically converted to SciPy’s `spmatrix` as needed and this conversion can be costly in terms of memory and performance as the operator size, mostly in terms of number of qubits it represents, gets larger. + + + + The class `qiskit.algorithms.eigen_solvers.numpy_eigen_solver.NumPyEigensolver` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.eigensolvers.NumPyEigensolver`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – How many eigenvalues are to be computed, has a min. value of 1. +* **filter\_criterion** (*Callable\[\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *| np.ndarray,*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*, ListOrDict\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None],* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*]*) – callable that allows to filter eigenvalues/eigenstates, only feasible eigenstates are returned in the results. The callable has the signature filter(eigenstate, eigenvalue, aux\_values) and must return a boolean to indicate whether to keep this value in the final returned result or not. If the number of elements that satisfies the criterion is smaller than k then the returned list has fewer elements and can even be empty. + +## Attributes + + + +### filter\_criterion + +returns the filter criterion if set + + + +### k + +returns k (number of eigenvalues requested) + +## Methods + +### compute\_eigenvalues + + + +`compute_eigenvalues(operator, aux_operators=None)` + +Computes eigenvalues. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +EigensolverResult + +**Return type** + +[EigensolverResult](qiskit.algorithms.EigensolverResult "qiskit.algorithms.EigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.NumPyMinimumEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.NumPyMinimumEigensolver.md new file mode 100644 index 00000000000..8ebc24d2b58 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.NumPyMinimumEigensolver.md @@ -0,0 +1,77 @@ +--- +title: NumPyMinimumEigensolver +description: API reference for qiskit.algorithms.NumPyMinimumEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.NumPyMinimumEigensolver +--- + +# NumPyMinimumEigensolver + + + +`qiskit.algorithms.NumPyMinimumEigensolver(filter_criterion=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigen_solvers/numpy_minimum_eigen_solver.py "view source code") + +Bases: [`MinimumEigensolver`](qiskit.algorithms.MinimumEigensolver "qiskit.algorithms.minimum_eigen_solvers.minimum_eigen_solver.MinimumEigensolver") + +Deprecated: Numpy Minimum Eigensolver algorithm. + +The NumPyMinimumEigensolver class has been superseded by the [`qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver") class. This class will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.minimum_eigen_solvers.numpy_minimum_eigen_solver.NumPyMinimumEigensolver` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +**filter\_criterion** (*Callable\[\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *| np.ndarray,*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*, ListOrDict\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None],* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*]*) – callable that allows to filter eigenvalues/eigenstates. The minimum eigensolver is only searching over feasible states and returns an eigenstate that has the smallest eigenvalue among feasible states. The callable has the signature filter(eigenstate, eigenvalue, aux\_values) and must return a boolean to indicate whether to consider this value or not. If there is no feasible element, the result can even be empty. + +## Attributes + + + +### filter\_criterion + +returns the filter criterion if set + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes minimum eigenvalue. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +MinimumEigensolverResult + +**Return type** + +[MinimumEigensolverResult](qiskit.algorithms.MinimumEigensolverResult "qiskit.algorithms.MinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.PVQD.md b/docs/api/qiskit/0.46/qiskit.algorithms.PVQD.md new file mode 100644 index 00000000000..f6e2ec0719e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.PVQD.md @@ -0,0 +1,232 @@ +--- +title: PVQD +description: API reference for qiskit.algorithms.PVQD +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.PVQD +--- + +# PVQD + + + +`qiskit.algorithms.PVQD(fidelity, ansatz, initial_parameters, estimator=None, optimizer=None, num_timesteps=None, evolution=None, use_parameter_shift=True, initial_guess=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/pvqd/pvqd.py "view source code") + +Bases: [`RealTimeEvolver`](qiskit.algorithms.RealTimeEvolver "qiskit.algorithms.time_evolvers.real_time_evolver.RealTimeEvolver") + +The projected Variational Quantum Dynamics (p-VQD) Algorithm. + +In each timestep, this algorithm computes the next state with a Trotter formula (specified by the `evolution` argument) and projects the timestep onto a variational form (`ansatz`). The projection is determined by maximizing the fidelity of the Trotter-evolved state and the ansatz, using a classical optimization routine. See Ref. \[1] for details. + +The following attributes can be set via the initializer but can also be read and updated once the PVQD object has been constructed. + + + +### ansatz + +The parameterized circuit representing the time-evolved state. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + + + +### initial\_parameters + +The parameters of the ansatz at time 0. + +**Type** + +np.ndarray + + + +### optimizer + +The classical optimization routine used to maximize the fidelity of the Trotter step and ansatz. + +**Type** + +Optional\[Union\[[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer"), [Minimizer](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer")]] + + + +### num\_timesteps + +The number of timesteps to take. If None, it is automatically selected to achieve a timestep of approximately 0.01. + +**Type** + +Optional\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + + + +### evolution + +The method to perform the Trotter step. Defaults to first-order Lie-Trotter evolution. + +**Type** + +Optional\[[EvolutionSynthesis](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis")] + + + +### use\_parameter\_shift + +If True, use the parameter shift rule for loss function gradients (if the ansatz supports). + +**Type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + + + +### initial\_guess + +The starting point for the first classical optimization run, at time 0. Defaults to random values in $[-0.01, 0.01]$. + +**Type** + +Optional\[np.ndarray] + +**Example** + +This snippet computes the real time evolution of a quantum Ising model on two neighboring sites and keeps track of the magnetization. + +```python +import numpy as np + +from qiskit.algorithms.state_fidelities import ComputeUncompute +from qiskit.algorithms.time_evolvers import TimeEvolutionProblem, PVQD +from qiskit.primitives import Estimator, Sampler +from qiskit.circuit.library import EfficientSU2 +from qiskit.quantum_info import SparsePauliOp, Pauli +from qiskit.algorithms.optimizers import L_BFGS_B + +sampler = Sampler() +fidelity = ComputeUncompute(sampler) +estimator = Estimator() +hamiltonian = 0.1 * SparsePauliOp(["ZZ", "IX", "XI"]) +observable = Pauli("ZZ") +ansatz = EfficientSU2(2, reps=1) +initial_parameters = np.zeros(ansatz.num_parameters) + +time = 1 +optimizer = L_BFGS_B() + +# setup the algorithm +pvqd = PVQD( + fidelity, + ansatz, + initial_parameters, + estimator, + num_timesteps=100, + optimizer=optimizer, +) + +# specify the evolution problem +problem = TimeEvolutionProblem( + hamiltonian, time, aux_operators=[hamiltonian, observable] +) + +# and evolve! +result = pvqd.evolve(problem) +``` + +**References** + +**\[1] Stefano Barison, Filippo Vicentini, and Giuseppe Carleo (2021), An efficient** + +quantum algorithm for the time evolution of parameterized circuits, [Quantum 5, 512](https://quantum-journal.org/papers/q-2021-07-28-512/). + +**Parameters** + +* **fidelity** ([*BaseStateFidelity*](qiskit.algorithms.state_fidelities.BaseStateFidelity "qiskit.algorithms.state_fidelities.BaseStateFidelity")) – A fidelity primitive used by the algorithm. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A parameterized circuit preparing the variational ansatz to model the time evolved quantum state. +* **initial\_parameters** (*np.ndarray*) – The initial parameters for the ansatz. Together with the ansatz, these define the initial state of the time evolution. +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") *| None*) – An estimator primitive used for calculating expected values of auxiliary operators (if provided via the problem). +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") *| None*) – The classical optimizers used to minimize the overlap between Trotterization and ansatz. Can be either a [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable using the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. This argument is optional since it is not required for [`get_loss()`](#qiskit.algorithms.PVQD.get_loss "qiskit.algorithms.PVQD.get_loss"), but it has to be set before [`evolve()`](#qiskit.algorithms.PVQD.evolve "qiskit.algorithms.PVQD.evolve") is called. +* **num\_timesteps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of time steps. If `None` it will be set such that the timestep is close to 0.01. +* **evolution** ([*EvolutionSynthesis*](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis") *| None*) – The evolution synthesis to use for the construction of the Trotter step. Defaults to first-order Lie-Trotter decomposition, see also `evolution` for different options. +* **use\_parameter\_shift** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, use the parameter shift rule to compute gradients. If False, the optimizer will not be passed a gradient callable. In that case, Qiskit optimizers will use a finite difference rule to approximate the gradients. +* **initial\_guess** (*np.ndarray | None*) – The initial guess for the first VQE optimization. Afterwards the previous iteration result is used as initial guess. If None, this is set to a random vector with elements in the interval $[-0.01, 0.01]$. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Perform real time evolution $\exp(-i t H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for a time $t$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – The evolution problem containing the hamiltonian, total evolution time and observables to evaluate. + +**Returns** + +A result object containing the evolution information and evaluated observables. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `aux_operators` provided in the time evolution problem but no estimator provided to the algorithm. +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If the evolution problem contains an initial state. + +**Return type** + +[*TimeEvolutionResult*](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + +### get\_loss + + + +`get_loss(hamiltonian, ansatz, dt, current_parameters)` + +Get a function to evaluate the infidelity between Trotter step and ansatz. + +**Parameters** + +* **hamiltonian** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – The Hamiltonian under which to evolve. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The parameterized quantum circuit which attempts to approximate the time-evolved state. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The time step. +* **current\_parameters** (*np.ndarray*) – The current parameters. + +**Returns** + +**A callable to evaluate the infidelity and, if gradients are supported and required,** + +a second callable to evaluate the gradient of the infidelity. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")], Callable\[\[np.ndarray], np.ndarray]] | None + +### step + + + +`step(hamiltonian, ansatz, theta, dt, initial_guess)` + +Perform a single time step. + +**Parameters** + +* **hamiltonian** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – The Hamiltonian under which to evolve. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The parameterized quantum circuit which attempts to approximate the time-evolved state. +* **theta** (*np.ndarray*) – The current parameters. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The time step. +* **initial\_guess** (*np.ndarray*) – The initial guess for the classical optimization of the fidelity between the next variational state and the Trotter-evolved last state. If None, this is set to a random vector with elements in the interval $[-0.01, 0.01]$. + +**Returns** + +A tuple consisting of the next parameters and the fidelity of the optimization. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[np.ndarray, [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.PVQDResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.PVQDResult.md new file mode 100644 index 00000000000..4bae482a186 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.PVQDResult.md @@ -0,0 +1,42 @@ +--- +title: PVQDResult +description: API reference for qiskit.algorithms.PVQDResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.PVQDResult +--- + +# PVQDResult + + + +`qiskit.algorithms.PVQDResult(evolved_state, aux_ops_evaluated=None, times=None, parameters=None, fidelities=None, estimated_error=None, observables=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/pvqd/pvqd_result.py "view source code") + +Bases: [`TimeEvolutionResult`](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + +The result object for the p-VQD algorithm. + +**Parameters** + +* **evolved\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – An evolved quantum state. +* **aux\_ops\_evaluated** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]] | None*) – Optional list of observables for which expected values on an evolved state are calculated. These values are in fact tuples formatted as (mean, standard deviation). +* **times** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – The times evaluated during the time integration. +* **parameters** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[np.ndarray] | None*) – The parameter values at each evaluation time. +* **fidelities** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – The fidelity of the Trotter step and variational update at each iteration. +* **estimated\_error** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The overall estimated error evaluated as one minus the product of all fidelities. +* **observables** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – The value of the observables evaluated at each iteration. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimation.md b/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimation.md new file mode 100644 index 00000000000..e32c2a64cb6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimation.md @@ -0,0 +1,128 @@ +--- +title: PhaseEstimation +description: API reference for qiskit.algorithms.PhaseEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.PhaseEstimation +--- + +# PhaseEstimation + + + +`qiskit.algorithms.PhaseEstimation(num_evaluation_qubits, quantum_instance=None, sampler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/phase_estimators/phase_estimation.py "view source code") + +Bases: `PhaseEstimator` + +Run the Quantum Phase Estimation (QPE) algorithm. + +This runs QPE with a multi-qubit register for reading the phases \[1] of input states. + +The algorithm takes as input a unitary $U$ and a state $|\psi\rangle$, which may be written + +$$ +|\psi\rangle = \sum_j c_j |\phi_j\rangle, +$$ + +where $|\phi_j\rangle$ are eigenstates of $U$. We prepare the quantum register in the state $|\psi\rangle$ then apply $U$ leaving the register in the state + +$$ +U|\psi\rangle = \sum_j \exp(i \phi_j) c_j |\phi_j\rangle. +$$ + +In the ideal case, one then measures the phase $\phi_j$ with probability $|c_j|^2$. In practice, many (or all) of the bit strings may be measured due to noise and the possibility that $\phi_j$ may not be representable exactly by the output register. In the latter case the probability for each eigenphase will be spread across bitstrings, with amplitudes that decrease with distance from the bitstring most closely approximating the eigenphase. + +The main input to the constructor is the number of qubits in the phase-reading register. For phase estimation, there are two methods: + +**first. estimate, which takes a state preparation circuit to prepare an input state, and** + +a unitary that will act on the input state. In this case, an instance of `qiskit.circuit.PhaseEstimation`, a QPE circuit, containing the state preparation and input unitary will be constructed. + +**second. estimate\_from\_pe\_circuit, which takes a quantum-phase-estimation circuit in which** + +the unitary and state preparation are already embedded. + +In both estimation methods, the QPE circuit is run on a backend and the frequencies or counts of the phases represented by bitstrings are recorded. The results are returned as an instance of `PhaseEstimationResult`. + +**Reference:** + +**\[1]: Michael A. Nielsen and Isaac L. Chuang. 2011.** + +Quantum Computation and Quantum Information: 10th Anniversary Edition (10th ed.). Cambridge University Press, New York, NY, USA. + + + `qiskit.algorithms.phase_estimators.phase_estimation.PhaseEstimation.__init__()`’s argument `quantum_instance` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the `sampler` argument. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **num\_evaluation\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits used in estimating the phase. The phase will be estimated as a binary string with this many bits. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Deprecated: The quantum instance on which the circuit will be run. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – The sampler primitive on which the circuit will be sampled. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If neither sampler nor quantum instance is provided. + +## Methods + +### construct\_circuit + + + +`construct_circuit(unitary, state_preparation=None)` + +Return the circuit to be executed to estimate phases. + +This circuit includes as sub-circuits the core phase estimation circuit, with the addition of the state-preparation circuit and possibly measurement instructions. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### estimate + + + +`estimate(unitary, state_preparation=None)` + +Build a phase estimation circuit and run the corresponding algorithm. + +**Parameters** + +* **unitary** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The circuit representing the unitary operator whose eigenvalues (via phase) will be measured. +* **state\_preparation** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – The circuit that prepares the state whose eigenphase will be measured. If this parameter is omitted, no preparation circuit will be run and input state will be the all-zero state in the computational basis. + +**Returns** + +An instance of qiskit.algorithms.phase\_estimator\_result.PhaseEstimationResult. + +**Return type** + +[PhaseEstimationResult](qiskit.algorithms.PhaseEstimationResult "qiskit.algorithms.PhaseEstimationResult") + +### estimate\_from\_pe\_circuit + + + +`estimate_from_pe_circuit(pe_circuit, num_unitary_qubits)` + +Run the phase estimation algorithm on a phase estimation circuit + +**Parameters** + +* **pe\_circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The phase estimation circuit. +* **num\_unitary\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Must agree with the number of qubits in the unitary in pe\_circuit. + +**Returns** + +An instance of qiskit.algorithms.phase\_estimator\_result.PhaseEstimationResult. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – Primitive job failed. + +**Return type** + +[*PhaseEstimationResult*](qiskit.algorithms.PhaseEstimationResult "qiskit.algorithms.phase_estimators.phase_estimation_result.PhaseEstimationResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationResult.md new file mode 100644 index 00000000000..d500ae05dd7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationResult.md @@ -0,0 +1,103 @@ +--- +title: PhaseEstimationResult +description: API reference for qiskit.algorithms.PhaseEstimationResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.PhaseEstimationResult +--- + +# PhaseEstimationResult + + + +`qiskit.algorithms.PhaseEstimationResult(num_evaluation_qubits, circuit_result, phases)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/phase_estimators/phase_estimation_result.py "view source code") + +Bases: `PhaseEstimatorResult` + +Store and manipulate results from running PhaseEstimation. + +This class is instantiated by the `PhaseEstimation` class, not via user code. The `PhaseEstimation` class generates a list of phases and corresponding weights. Upon completion it returns the results as an instance of this class. The main method for accessing the results is filter\_phases. + +The canonical phase satisfying the `PhaseEstimator` interface, returned by the attribute phase, is the most likely phase. + +**Parameters** + +* **num\_evaluation\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits in phase-readout register. +* **circuit\_result** ([*Result*](qiskit.result.Result "qiskit.result.Result")) – result object returned by method running circuit. +* **phases** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – ndarray or dict of phases and frequencies determined by QPE. + +## Attributes + + + +### circuit\_result + +Return the result object returned by running the QPE circuit (on hardware or simulator). + +This is useful for inspecting and troubleshooting the QPE algorithm. + + + +### most\_likely\_phase + +DEPRECATED - Return the most likely phase as a number in $[0.0, 1.0)$. + +1.0 corresponds to a phase of $2\pi$. This selects the phase corresponding to the bit string with the highesest probability. This is the most likely phase. + + + The property `qiskit.algorithms.phase_estimators.phase_estimation_result.PhaseEstimationResult.most_likely_phase` is deprecated as of qiskit-terra 0.18.0. It will be removed no earlier than 3 months after the release date. Instead, use the property `phase`, which behaves the same. + + + + +### phase + +Return the most likely phase as a number in $[0.0, 1.0)$. + +1.0 corresponds to a phase of $2\pi$. This selects the phase corresponding to the bit string with the highesest probability. This is the most likely phase. + + + +### phases + +Return all phases and their frequencies computed by QPE. + +This is an array or dict whose values correspond to weights on bit strings. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + +### filter\_phases + + + +`filter_phases(cutoff=0.0, as_float=True)` + +Return a filtered dict of phases (keys) and frequencies (values). + +Only phases with frequencies (counts) larger than cutoff are included. It is assumed that the run method has been called so that the phases have been computed. When using a noiseless, shot-based simulator to read a single phase that can be represented exactly by num\_evaluation\_qubits, all the weight will be concentrated on a single phase. In all other cases, many, or all, bit strings will have non-zero weight. This method is useful for filtering out these uninteresting bit strings. + +**Parameters** + +* **cutoff** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Minimum weight of number of counts required to keep a bit string. The default value is 0.0. +* **as\_float** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, returned keys are floats in $[0.0, 1.0)$. If False returned keys are bit strings. + +**Returns** + +A filtered dict of phases (keys) and frequencies (values). + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationScale.md b/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationScale.md new file mode 100644 index 00000000000..ecbf2957b8f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.PhaseEstimationScale.md @@ -0,0 +1,116 @@ +--- +title: PhaseEstimationScale +description: API reference for qiskit.algorithms.PhaseEstimationScale +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.PhaseEstimationScale +--- + +# PhaseEstimationScale + + + +`qiskit.algorithms.PhaseEstimationScale(bound)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/phase_estimators/phase_estimation_scale.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Set and use a bound on eigenvalues of a Hermitian operator in order to ensure phases are in the desired range and to convert measured phases into eigenvectors. + +The `bound` is set when constructing this class. Then the method `scale` is used to find the factor by which to scale the operator. + +If `bound` is equal exactly to the largest eigenvalue, and the smallest eigenvalue is minus the largest, then these two eigenvalues will not be distinguished. For example, if the Hermitian operator is the Pauli Z operator with eigenvalues $1$ and $-1$, and `bound` is $1$, then both eigenvalues will be mapped to $1$. This can be avoided by making `bound` a bit larger. + +Increasing `bound` decreases the part of the interval $[0, 1)$ that is used to map eigenvalues to `phi`. However, sometimes this results in a better determination of the eigenvalues, because 1) although there are fewer discrete phases in the useful range, it may shift one of the discrete phases closer to the actual phase. And, 2) If one of the discrete phases is close to, or exactly equal to the actual phase, then artifacts (probability) in neighboring phases will be reduced. This is important because the artifacts may be larger than the probability in a phase representing another eigenvalue of interest whose corresponding eigenstate has a relatively small weight in the input state. + +**Parameters** + +**bound** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – an upper bound on the absolute value of the eigenvalues of a Hermitian operator. (The operator is not needed here.) + +## Attributes + + + +### scale + +Return the Hamiltonian scaling factor. + +Return the scale factor by which a Hermitian operator must be multiplied so that the phase of the corresponding unitary is restricted to $[-\pi, \pi]$. This factor is computed from the bound on the absolute values of the eigenvalues of the operator. The methods `scale_phase` and `scale_phases` are used recover the eigenvalues corresponding the original (unscaled) Hermitian operator. + +**Returns** + +The scale factor. + +## Methods + +### from\_pauli\_sum + + + +`classmethod from_pauli_sum(pauli_sum)` + +Create a PhaseEstimationScale from a SummedOp representing a sum of Pauli Operators. + +It is assumed that the `pauli_sum` is the sum of `PauliOp` objects. The bound on the absolute value of the eigenvalues of the sum is obtained as the sum of the absolute values of the coefficients of the terms. This is the best bound available in the generic case. A `PhaseEstimationScale` object is instantiated using this bound. + +**Parameters** + +**pauli\_sum** ([*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") *|*[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – A `SummedOp` whose terms are `PauliOp` objects. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if `pauli_sum` is not a sum of Pauli operators. + +**Returns** + +A `PhaseEstimationScale` object + +**Return type** + +‘PhaseEstimationScale’ | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### scale\_phase + + + +`scale_phase(phi, id_coefficient=0.0)` + +Convert a phase into an eigenvalue. + +The input phase `phi` corresponds to the eigenvalue of a unitary obtained by exponentiating a scaled Hermitian operator. Recall that the phase is obtained from `phi` as $2\pi\phi$. Furthermore, the Hermitian operator was scaled so that `phi` is restricted to $[-1/2, 1/2]$, corresponding to phases in $[-\pi, \pi]$. But the values of phi read from the phase-readout register are in $[0, 1)$. Any value of `phi` greater than $1/2$ corresponds to a raw phase of minus the complement with respect to 1. After this possible shift, the phase is scaled by the inverse of the factor by which the Hermitian operator was scaled to recover the eigenvalue of the Hermitian operator. + +**Parameters** + +* **phi** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Normalized phase in $[0, 1)$ to be converted to an eigenvalue. +* **id\_coefficient** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – All eigenvalues are shifted by this value. + +**Returns** + +An eigenvalue computed from the input phase. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### scale\_phases + + + +`scale_phases(phases, id_coefficient=0.0)` + +Convert a list or dict of phases to eigenvalues. + +The values in the list, or keys in the dict, are values of ```phi` and are converted as described in the description of ``scale_phase```. In case `phases` is a dict, the values of the dict are passed unchanged. + +**Parameters** + +* **phases** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – a list or dict of values of `phi`. +* **id\_coefficient** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – All eigenvalues are shifted by this value. + +**Returns** + +Eigenvalues computed from phases. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.QAOA.md b/docs/api/qiskit/0.46/qiskit.algorithms.QAOA.md new file mode 100644 index 00000000000..6f1fb3443bc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.QAOA.md @@ -0,0 +1,252 @@ +--- +title: QAOA +description: API reference for qiskit.algorithms.QAOA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.QAOA +--- + +# QAOA + + + +`qiskit.algorithms.QAOA(optimizer=None, reps=1, initial_state=None, mixer=None, initial_point=None, gradient=None, expectation=None, include_custom=False, max_evals_grouped=1, callback=None, quantum_instance=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigen_solvers/qaoa.py "view source code") + +Bases: [`VQE`](qiskit.algorithms.VQE "qiskit.algorithms.minimum_eigen_solvers.vqe.VQE") + +Deprecated: Quantum Approximate Optimization Algorithm. + +The QAOA class has been superseded by the [`qiskit.algorithms.minimum_eigensolvers.QAOA`](qiskit.algorithms.minimum_eigensolvers.QAOA "qiskit.algorithms.minimum_eigensolvers.QAOA") class. This class will be deprecated in a future release and subsequently removed after that. + +[QAOA](https://arxiv.org/abs/1411.4028) is a well-known algorithm for finding approximate solutions to combinatorial-optimization problems. + +The QAOA implementation directly extends [`VQE`](qiskit.algorithms.VQE "qiskit.algorithms.VQE") and inherits VQE’s optimization structure. However, unlike VQE, which can be configured with arbitrary ansatzes, QAOA uses its own fine-tuned ansatz, which comprises $p$ parameterized global $x$ rotations and $p$ different parameterizations of the problem hamiltonian. QAOA is thus principally configured by the single integer parameter, *p*, which dictates the depth of the ansatz, and thus affects the approximation quality. + +An optional array of $2p$ parameter values, as the *initial\_point*, may be provided as the starting **beta** and **gamma** parameters (as identically named in the original [QAOA paper](https://arxiv.org/abs/1411.4028)) for the QAOA ansatz. + +An operator or a parameterized quantum circuit may optionally also be provided as a custom mixer Hamiltonian. This allows, as discussed in [this paper](https://doi.org/10.1103/PhysRevApplied.5.034007) for quantum annealing, and in [this paper](https://arxiv.org/abs/1709.03489) for QAOA, to run constrained optimization problems where the mixer constrains the evolution to a feasible subspace of the full Hilbert space. + + + The class `qiskit.algorithms.minimum_eigen_solvers.qaoa.QAOA` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.minimum_eigensolvers.QAOA`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") *| None*) – A classical optimizer, see also [`VQE`](qiskit.algorithms.VQE "qiskit.algorithms.VQE") for more details on the possible types. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the integer parameter $p$ as specified in [https://arxiv.org/abs/1411.4028](https://arxiv.org/abs/1411.4028), Has a minimum valid value of 1. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – An optional initial state to prepend the QAOA circuit with +* **mixer** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – the mixer Hamiltonian to evolve with or a custom quantum circuit. Allows support of optimizations in constrained subspaces as per [https://arxiv.org/abs/1709.03489](https://arxiv.org/abs/1709.03489) as well as warm-starting the optimization as introduced in [http://arxiv.org/abs/2009.10095](http://arxiv.org/abs/2009.10095). +* **initial\_point** (*np.ndarray | None*) – An optional initial point (i.e. initial parameter values) for the optimizer. If `None` then it will simply compute a random one. +* **gradient** ([*GradientBase*](qiskit.opflow.gradients.GradientBase "qiskit.opflow.gradients.GradientBase") *| Callable\[\[np.ndarray |*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*],* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*] | None*) – An optional gradient operator respectively a gradient function used for optimization. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase") *| None*) – The Expectation converter for taking the average value of the Observable over the ansatz state function. When None (the default) an [`ExpectationFactory`](qiskit.opflow.expectations.ExpectationFactory "qiskit.opflow.expectations.ExpectationFactory") is used to select an appropriate expectation based on the operator and backend. When using Aer qasm\_simulator backend, with paulis, it is however much faster to leverage custom Aer function for the computation but, although VQE performs much faster with it, the outcome is ideal, with no shot noise, like using a state vector simulator. If you are just looking for the quickest performance when choosing Aer qasm\_simulator and the lack of shot noise is not an issue then set include\_custom parameter here to True (defaults to False). +* **include\_custom** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When expectation parameter here is None setting this to True will allow the factory to include the custom Aer pauli expectation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of evaluations performed simultaneously. Signals the given optimizer that more than one set of parameters can be supplied so that potentially the expectation values can be computed in parallel. Typically this is possible when a finite difference gradient is used by the optimizer such that multiple points to compute the gradient can be passed and if computed in parallel improve overall execution time. Ignored if a gradient operator or function is given. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*], None] | None*) – a callback that can access the intermediate data during the optimization. Four parameter values are passed to the callback as follows during each evaluation by the optimizer for its current set of parameters as it works towards the minimum. These are: the evaluation count, the optimizer parameters for the ansatz, the evaluated mean and the evaluated standard deviation. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Quantum Instance or Backend + +## Attributes + + + +### ansatz + +Returns the ansatz. + + + +### callback + +Returns callback + + + +### expectation + +The expectation value algorithm used to construct the expectation measurement from the observable. + + + +### gradient + +Returns the gradient. + + + +### include\_custom + +Returns include\_custom + + + +### initial\_point + +Returns initial point + + + +### initial\_state + +Returns: Returns the initial state. + + + +### max\_evals\_grouped + +Returns max\_evals\_grouped + + + +### mixer + +Returns: Returns the mixer. + + + +### optimizer + +Returns optimizer + + + +### quantum\_instance + +Returns quantum instance. + + + +### setting + +Prepare the setting of VQE as a string. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes minimum eigenvalue. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +MinimumEigensolverResult + +**Return type** + +[MinimumEigensolverResult](qiskit.algorithms.MinimumEigensolverResult "qiskit.algorithms.MinimumEigensolverResult") + +### construct\_circuit + + + +`construct_circuit(parameter, operator)` + +Return the circuits used to compute the expectation value. + +**Parameters** + +* **parameter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | np.ndarray*) – Parameters for the ansatz circuit. +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable + +**Returns** + +A list of the circuits used to compute the expectation value. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")] + +### construct\_expectation + + + +`construct_expectation(parameter, operator, return_expectation=False)` + +Generate the ansatz circuit and expectation value measurement, and return their runnable composition. + +**Parameters** + +* **parameter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | np.ndarray*) – Parameters for the ansatz circuit. +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **return\_expectation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, return the `ExpectationBase` expectation converter used in the construction of the expectation value. Useful e.g. to compute the standard deviation of the expectation value. + +**Returns** + +The Operator equalling the measurement of the ansatz `StateFn` by the Observable’s expectation `StateFn`, and, optionally, the expectation converter. + +**Raises** + +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If no operator has been provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If no expectation is passed and None could be inferred via the ExpectationFactory. + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase"), [ExpectationBase](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")] + +### get\_energy\_evaluation + + + +`get_energy_evaluation(operator, return_expectation=False)` + +Returns a function handle to evaluates the energy at given parameters for the ansatz. + +This is the objective function to be passed to the optimizer that is used for evaluation. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – The operator whose energy to evaluate. +* **return\_expectation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, return the `ExpectationBase` expectation converter used in the construction of the expectation value. Useful e.g. to evaluate other operators with the same expectation value converter. + +**Returns** + +Energy of the hamiltonian of each parameter, and, optionally, the expectation converter. + +**Raises** + +[**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.12)") – If the circuit is not parameterized (i.e. has 0 free parameters). + +**Return type** + +Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]], [ExpectationBase](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")] + +### print\_settings + + + +`print_settings()` + +Preparing the setting of VQE into a string. + +**Returns** + +the formatted setting of VQE + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.RealEvolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.RealEvolver.md new file mode 100644 index 00000000000..9f3765e6997 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.RealEvolver.md @@ -0,0 +1,48 @@ +--- +title: RealEvolver +description: API reference for qiskit.algorithms.RealEvolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.RealEvolver +--- + +# RealEvolver + + + +`qiskit.algorithms.RealEvolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/evolvers/real_evolver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: Interface for Quantum Real Time Evolution. + +The RealEvolver interface has been superseded by the `qiskit.algorithms.time_evolvers.RealTimeEvolver` interface. This interface will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.evolvers.real_evolver.RealEvolver` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the interface `qiskit.algorithms.time_evolvers.RealTimeEvolver`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Methods + +### evolve + + + +`abstract evolve(evolution_problem)` + +Perform real time evolution $\exp(-i t H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for a time $t$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*EvolutionProblem*](qiskit.algorithms.EvolutionProblem "qiskit.algorithms.evolvers.evolution_problem.EvolutionProblem")) – The definition of the evolution problem. + +**Returns** + +Evolution result which includes an evolved quantum state. + +**Return type** + +[*EvolutionResult*](qiskit.algorithms.EvolutionResult "qiskit.algorithms.evolvers.evolution_result.EvolutionResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.RealTimeEvolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.RealTimeEvolver.md new file mode 100644 index 00000000000..9ff195c72a6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.RealTimeEvolver.md @@ -0,0 +1,42 @@ +--- +title: RealTimeEvolver +description: API reference for qiskit.algorithms.RealTimeEvolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.RealTimeEvolver +--- + +# RealTimeEvolver + + + +`qiskit.algorithms.RealTimeEvolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/real_time_evolver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Interface for Quantum Real Time Evolution. + +## Methods + +### evolve + + + +`abstract evolve(evolution_problem)` + +Perform real time evolution $\exp(-i t H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for a time $t$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – The definition of the evolution problem. + +**Returns** + +Evolution result which includes an evolved quantum state. + +**Return type** + +[*TimeEvolutionResult*](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.SciPyImaginaryEvolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.SciPyImaginaryEvolver.md new file mode 100644 index 00000000000..dc36939ecd0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.SciPyImaginaryEvolver.md @@ -0,0 +1,52 @@ +--- +title: SciPyImaginaryEvolver +description: API reference for qiskit.algorithms.SciPyImaginaryEvolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.SciPyImaginaryEvolver +--- + +# SciPyImaginaryEvolver + + + +`qiskit.algorithms.SciPyImaginaryEvolver(num_timesteps)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/classical_methods/scipy_imaginary_evolver.py "view source code") + +Bases: [`ImaginaryTimeEvolver`](qiskit.algorithms.ImaginaryTimeEvolver "qiskit.algorithms.time_evolvers.imaginary_time_evolver.ImaginaryTimeEvolver") + +Classical Evolver for imaginary time evolution. + +Evolves an initial state $|\Psi\rangle$ for an imaginary time $\tau = it$ under a Hamiltonian $H$, as provided in the `evolution_problem`. Note that the precision of the evolver does not depend on the number of timesteps taken. + +**Parameters** + +**num\_timesteps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of timesteps in the simulation. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If num\_timesteps is not a positive integer. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Perform imaginary time evolution $\exp(-\tau H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for an imaginary time $\tau$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – The definition of the evolution problem. + +**Returns** + +Evolution result which includes an evolved quantum state. + +**Return type** + +[*TimeEvolutionResult*](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.SciPyRealEvolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.SciPyRealEvolver.md new file mode 100644 index 00000000000..04b53286b88 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.SciPyRealEvolver.md @@ -0,0 +1,52 @@ +--- +title: SciPyRealEvolver +description: API reference for qiskit.algorithms.SciPyRealEvolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.SciPyRealEvolver +--- + +# SciPyRealEvolver + + + +`qiskit.algorithms.SciPyRealEvolver(num_timesteps)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/classical_methods/scipy_real_evolver.py "view source code") + +Bases: [`RealTimeEvolver`](qiskit.algorithms.RealTimeEvolver "qiskit.algorithms.time_evolvers.real_time_evolver.RealTimeEvolver") + +Classical Evolver for real time evolution. + +Evolves an initial state $|\Psi\rangle$ for a time $t$ under a Hamiltonian $H$, as provided in the `evolution_problem`. Note that the precision of the evolver does not depend on the number of timesteps taken. + +**Parameters** + +**num\_timesteps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of timesteps in the simulation. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If steps is not a positive integer. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Perform real time evolution $\exp(-i t H)|\Psi\rangle$. + +Evolves an initial state $|\Psi\rangle$ for a time $t$ under a Hamiltonian $H$, as provided in the `evolution_problem`. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – The definition of the evolution problem. + +**Returns** + +Evolution result which includes an evolved quantum state. + +**Return type** + +[*TimeEvolutionResult*](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionProblem.md b/docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionProblem.md new file mode 100644 index 00000000000..f19ac2c85e2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionProblem.md @@ -0,0 +1,116 @@ +--- +title: TimeEvolutionProblem +description: API reference for qiskit.algorithms.TimeEvolutionProblem +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.TimeEvolutionProblem +--- + +# TimeEvolutionProblem + + + +`qiskit.algorithms.TimeEvolutionProblem(hamiltonian, time, initial_state=None, aux_operators=None, truncation_threshold=1e-12, t_param=None, param_value_map=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/time_evolution_problem.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Time evolution problem class. + +This class is the input to time evolution algorithms and must contain information on the total evolution time, a quantum state to be evolved and under which Hamiltonian the state is evolved. + + + +### hamiltonian + +The Hamiltonian under which to evolve the system. + +**Type** + +BaseOperator | [PauliSumOp](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") + + + +### initial\_state + +The quantum state to be evolved for methods like Trotterization. For variational time evolutions, where the evolution happens in an ansatz, this argument is not required. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") | [Statevector](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") | None + + + +### aux\_operators + +Optional list of auxiliary operators to be evaluated with the evolved `initial_state` and their expectation values returned. + +**Type** + +ListOrDict\[BaseOperator | [PauliSumOp](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")] | None + + + +### truncation\_threshold + +Defines a threshold under which values can be assumed to be 0. Used when `aux_operators` is provided. + +**Type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + + + +### t\_param + +Time parameter in case of a time-dependent Hamiltonian. This free parameter must be within the `hamiltonian`. + +**Type** + +[Parameter](qiskit.circuit.Parameter "qiskit.circuit.Parameter") | None + + + +### param\_value\_map + +Maps free parameters in the problem to values. Depending on the algorithm, it might refer to e.g. a Hamiltonian or an initial state. + +**Type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[Parameter](qiskit.circuit.Parameter "qiskit.circuit.Parameter"), [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")] | None + +**Parameters** + +* **hamiltonian** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – The Hamiltonian under which to evolve the system. +* **time** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Total time of evolution. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *| None*) – The quantum state to be evolved for methods like Trotterization. For variational time evolutions, where the evolution happens in an ansatz, this argument is not required. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the evolved `initial_state` and their expectation values returned. +* **truncation\_threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Defines a threshold under which values can be assumed to be 0. Used when `aux_operators` is provided. +* **t\_param** ([*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter") *| None*) – Time parameter in case of a time-dependent Hamiltonian. This free parameter must be within the `hamiltonian`. +* **param\_value\_map** (*Mapping\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] | None*) – Maps free parameters in the problem to values. Depending on the algorithm, it might refer to e.g. a Hamiltonian or an initial state. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If non-positive time of evolution is provided. + +## Attributes + + + +### time + +Returns time. + +## Methods + +### validate\_params + + + +`validate_params()` + +Checks if all parameters present in the Hamiltonian are also present in the dictionary that maps them to values. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If Hamiltonian parameters cannot be bound with data provided. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionResult.md new file mode 100644 index 00000000000..3000cb287b0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.TimeEvolutionResult.md @@ -0,0 +1,79 @@ +--- +title: TimeEvolutionResult +description: API reference for qiskit.algorithms.TimeEvolutionResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.TimeEvolutionResult +--- + +# TimeEvolutionResult + + + +`qiskit.algorithms.TimeEvolutionResult(evolved_state, aux_ops_evaluated=None, observables=None, times=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/time_evolution_result.py "view source code") + +Bases: `AlgorithmResult` + +Class for holding time evolution result. + + + +### evolved\_state + +An evolved quantum state. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")|[Statevector](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + + + +### aux\_ops\_evaluated + +Optional list of observables for which expected values on an evolved state are calculated. These values are in fact tuples formatted as (mean, standard deviation). + +**Type** + +ListOrDict\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)"), [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")]] | None + + + +### observables + +Optional list of observables for which expected on an evolved state are calculated at each timestep. These values are in fact lists of tuples formatted as (mean, standard deviation). + +**Type** + +ListOrDict\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[np.ndarray, np.ndarray]] | None + + + +### times + +Optional list of times at which each observable has been evaluated. + +**Type** + +np.array | None + +**Parameters** + +* **evolved\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – An evolved quantum state. +* **aux\_ops\_evaluated** (*ListOrDict\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]] | None*) – Optional list of observables for which expected values on an evolved state are calculated. These values are in fact tuples formatted as (mean, standard deviation). +* **observables** (*ListOrDict\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[np.ndarray, np.ndarray]] | None*) – Optional list of observables for which expected values are calculated for each timestep. These values are in fact tuples formatted as (mean array, standard deviation array). +* **times** (*np.ndarray | None*) – Optional list of times at which each observable has been evaluated. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.TrotterQRTE.md b/docs/api/qiskit/0.46/qiskit.algorithms.TrotterQRTE.md new file mode 100644 index 00000000000..18315511224 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.TrotterQRTE.md @@ -0,0 +1,120 @@ +--- +title: TrotterQRTE +description: API reference for qiskit.algorithms.TrotterQRTE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.TrotterQRTE +--- + +# TrotterQRTE + + + +`qiskit.algorithms.TrotterQRTE(product_formula=None, expectation=None, quantum_instance=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/evolvers/trotterization/trotter_qrte.py "view source code") + +Bases: [`RealEvolver`](qiskit.algorithms.RealEvolver "qiskit.algorithms.evolvers.real_evolver.RealEvolver") + +Deprecated: Quantum Real Time Evolution using Trotterization. + +The TrotterQRTE class has been superseded by the [`qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE`](qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE "qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE") class. This class will be deprecated in a future release and subsequently removed after that. + +Type of Trotterization is defined by a ProductFormula provided. + +Examples: + +```python +from qiskit.opflow import X, Z, Zero +from qiskit.algorithms import EvolutionProblem, TrotterQRTE +from qiskit import BasicAer +from qiskit.utils import QuantumInstance + +operator = X + Z +initial_state = Zero +time = 1 +evolution_problem = EvolutionProblem(operator, 1, initial_state) +# LieTrotter with 1 rep +backend = BasicAer.get_backend("statevector_simulator") +quantum_instance = QuantumInstance(backend=backend) +trotter_qrte = TrotterQRTE(quantum_instance=quantum_instance) +evolved_state = trotter_qrte.evolve(evolution_problem).evolved_state +``` + + + The class `qiskit.algorithms.evolvers.trotterization.trotter_qrte.TrotterQRTE` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **product\_formula** ([*ProductFormula*](qiskit.synthesis.ProductFormula "qiskit.synthesis.ProductFormula") *| None*) – A Lie-Trotter-Suzuki product formula. The default is the Lie-Trotter first order product formula with a single repetition. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase") *| None*) – An instance of ExpectationBase which defines a method for calculating expectation values of EvolutionProblem.aux\_operators. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – A quantum instance used for calculating expectation values of EvolutionProblem.aux\_operators. + +## Attributes + + + +### expectation + +Returns an expectation used in the algorithm. + + + +### product\_formula + +Returns a product formula used in the algorithm. + + + +### quantum\_instance + +Returns a quantum instance used in the algorithm. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Evolves a quantum state for a given time using the Trotterization method based on a product formula provided. The result is provided in the form of a quantum circuit. If auxiliary operators are included in the `evolution_problem`, they are evaluated on an evolved state using a backend provided. + + + Time-dependent Hamiltonians are not yet supported. + + +**Parameters** + +**evolution\_problem** ([*EvolutionProblem*](qiskit.algorithms.EvolutionProblem "qiskit.algorithms.evolvers.evolution_problem.EvolutionProblem")) – Instance defining evolution problem. For the included Hamiltonian, `PauliOp`, `SummedOp` or `PauliSumOp` are supported by TrotterQRTE. + +**Returns** + +Evolution result that includes an evolved state as a quantum circuit and, optionally, auxiliary operators evaluated for a resulting state on a backend. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `t_param` is not set to None in the EvolutionProblem (feature not currently supported). +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the `initial_state` is not provided in the EvolutionProblem. + +**Return type** + +[*EvolutionResult*](qiskit.algorithms.EvolutionResult "qiskit.algorithms.evolvers.evolution_result.EvolutionResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +**Returns** + +**True if `aux_operators` expectations in the EvolutionProblem can be evaluated, False** + +otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.VQD.md b/docs/api/qiskit/0.46/qiskit.algorithms.VQD.md new file mode 100644 index 00000000000..1e31358f840 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.VQD.md @@ -0,0 +1,243 @@ +--- +title: VQD +description: API reference for qiskit.algorithms.VQD +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.VQD +--- + +# VQD + + + +`qiskit.algorithms.VQD(ansatz=None, k=2, betas=None, optimizer=None, initial_point=None, gradient=None, expectation=None, include_custom=False, max_evals_grouped=1, callback=None, quantum_instance=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigen_solvers/vqd.py "view source code") + +Bases: `VariationalAlgorithm`, [`Eigensolver`](qiskit.algorithms.Eigensolver "qiskit.algorithms.eigen_solvers.eigen_solver.Eigensolver") + +Deprecated: Variational Quantum Deflation algorithm. + +The VQD class has been superseded by the [`qiskit.algorithms.eigensolvers.VQD`](qiskit.algorithms.eigensolvers.VQD "qiskit.algorithms.eigensolvers.VQD") class. This class will be deprecated in a future release and subsequently removed after that. + +[VQD](https://arxiv.org/abs/1805.08138) is a quantum algorithm that uses a variational technique to find the k eigenvalues of the Hamiltonian $H$ of a given system. + +The algorithm computes excited state energies of generalised hamiltonians by optimising over a modified cost function where each succesive eigen value is calculated iteratively by introducing an overlap term with all the previously computed eigenstaes that must be minimised, thus ensuring higher energy eigen states are found. + +An instance of VQD requires defining three algorithmic sub-components: an integer k denoting the number of eigenstates to calculate, a trial state (a.k.a. ansatz)which is a `QuantumCircuit`, and one of the classical [`optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers"). The ansatz is varied, via its set of parameters, by the optimizer, such that it works towards a state, as determined by the parameters applied to the ansatz, that will result in the minimum expectation values being measured of the input operator (Hamiltonian). The algorithm does this by iteratively refining each excited state to be orthogonal to all the previous excited states. + +An optional array of parameter values, via the *initial\_point*, may be provided as the starting point for the search of the minimum eigenvalue. This feature is particularly useful such as when there are reasons to believe that the solution point is close to a particular point. + +The length of the *initial\_point* list value must match the number of the parameters expected by the ansatz being used. If the *initial\_point* is left at the default of `None`, then VQD will look to the ansatz for a preferred value, based on its given initial state. If the ansatz returns `None`, then a random point will be generated within the parameter bounds set, as per above. If the ansatz provides `None` as the lower bound, then VQD will default it to $-2\pi$; similarly, if the ansatz returns `None` as the upper bound, the default value will be $2\pi$. + + + The class `qiskit.algorithms.eigen_solvers.vqd.VQD` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.eigensolvers.VQD`.See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A parameterized circuit used as ansatz for the wave function. +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of eigenvalues to return. Returns the lowest k eigenvalues. +* **betas** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – beta parameters in the VQD paper. Should have length k - 1, with k the number of excited states. These hyperparameters balance the contribution of each overlap term to the cost function and have a default value computed as the mean square sum of the coefficients of the observable. +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") *| None*) – A classical optimizer. Can either be a Qiskit optimizer or a callable that takes an array as input and returns a Qiskit or SciPy optimization result. +* **initial\_point** (*np.ndarray | None*) – An optional initial point (i.e. initial parameter values) for the optimizer. If `None` then VQD will look to the ansatz for a preferred point and if not will simply compute a random one. +* **gradient** ([*GradientBase*](qiskit.opflow.gradients.GradientBase "qiskit.opflow.gradients.GradientBase") *| Callable | None*) – An optional gradient function or operator for optimizer. Only used to compute the ground state at the moment. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase") *| None*) – The Expectation converter for taking the average value of the Observable over the ansatz state function. When `None` (the default) an [`ExpectationFactory`](qiskit.opflow.expectations.ExpectationFactory "qiskit.opflow.expectations.ExpectationFactory") is used to select an appropriate expectation based on the operator and backend. When using Aer qasm\_simulator backend, with paulis, it is however much faster to leverage custom Aer function for the computation but, although VQD performs much faster with it, the outcome is ideal, with no shot noise, like using a state vector simulator. If you are just looking for the quickest performance when choosing Aer qasm\_simulator and the lack of shot noise is not an issue then set include\_custom parameter here to `True` (defaults to `False`). +* **include\_custom** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When expectation parameter here is None setting this to `True` will allow the factory to include the custom Aer pauli expectation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of evaluations performed simultaneously. Signals the given optimizer that more than one set of parameters can be supplied so that multiple points to compute the gradient can be passed and if computed in parallel potentially the expectation values can be computed in parallel. Typically this is possible when a finite difference gradient is used by the optimizer such that improve overall execution time. Deprecated if a gradient operator or function is given. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*], None] | None*) – a callback that can access the intermediate data during the optimization. Four parameter values are passed to the callback as follows during each evaluation by the optimizer for its current set of parameters as it works towards the minimum. These are: the evaluation count, the optimizer parameters for the ansatz, the evaluated mean, the evaluated standard deviation, and the current step. +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Quantum Instance or Backend + +## Attributes + + + +### ansatz + +Returns the ansatz. + + + +### callback + +Returns callback + + + +### expectation + +The expectation value algorithm used to construct the expectation measurement from the observable. + + + +### gradient + +Returns the gradient. + + + +### include\_custom + +Returns include\_custom + + + +### initial\_point + +Returns initial point. + + + +### max\_evals\_grouped + +Returns max\_evals\_grouped + + + +### optimizer + +Returns optimizer + + + +### quantum\_instance + +Returns quantum instance. + + + +### setting + +Prepare the setting of VQD as a string. + +## Methods + +### compute\_eigenvalues + + + +`compute_eigenvalues(operator, aux_operators=None)` + +Computes eigenvalues. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +EigensolverResult + +**Return type** + +[EigensolverResult](qiskit.algorithms.EigensolverResult "qiskit.algorithms.EigensolverResult") + +### construct\_circuit + + + +`construct_circuit(parameter, operator)` + +Return the circuits used to compute the expectation value. + +**Parameters** + +* **parameter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | np.ndarray*) – Parameters for the ansatz circuit. +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable + +**Returns** + +A list of the circuits used to compute the expectation value. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")] + +### construct\_expectation + + + +`construct_expectation(parameter, operator, return_expectation=False)` + +Generate the ansatz circuit and expectation value measurement, and return their runnable composition. + +**Parameters** + +* **parameter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | np.ndarray*) – Parameters for the ansatz circuit. +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **return\_expectation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, return the `ExpectationBase` expectation converter used in the construction of the expectation value. Useful e.g. to compute the standard deviation of the expectation value. + +**Returns** + +The Operator equalling the measurement of the ansatz `StateFn` by the Observable’s expectation `StateFn`, and, optionally, the expectation converter. + +**Raises** + +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If no operator has been provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If no expectation is passed and None could be inferred via the ExpectationFactory. + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase"), [ExpectationBase](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")] + +### get\_energy\_evaluation + + + +`get_energy_evaluation(step, operator, return_expectation=False, prev_states=None)` + +Returns a function handle to evaluates the energy at given parameters for the ansatz. + +This return value is the objective function to be passed to the optimizer for evaluation. + +**Parameters** + +* **step** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – level of energy being calculated. 0 for ground, 1 for first excited state… +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – The operator whose energy to evaluate. +* **return\_expectation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, return the `ExpectationBase` expectation converter used in the construction of the expectation value. Useful e.g. to evaluate other operators with the same expectation value converter. +* **prev\_states** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[np.ndarray] | None*) – List of parameters from previous rounds of optimization. + +**Returns** + +A callable that computes and returns the energy of the hamiltonian of each parameter, and, optionally, the expectation + +**Raises** + +* [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.12)") – If the circuit is not parameterized (i.e. has 0 free parameters). +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If operator was not provided. + +**Return type** + +Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]], [ExpectationBase](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")] + +### print\_settings + + + +`print_settings()` + +Preparing the setting of VQD into a string. + +**Returns** + +the formatted setting of VQD. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.VQDResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.VQDResult.md new file mode 100644 index 00000000000..d89e9745884 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.VQDResult.md @@ -0,0 +1,108 @@ +--- +title: VQDResult +description: API reference for qiskit.algorithms.VQDResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.VQDResult +--- + +# VQDResult + + + +`qiskit.algorithms.VQDResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigen_solvers/vqd.py "view source code") + +Bases: `VariationalResult`, [`EigensolverResult`](qiskit.algorithms.EigensolverResult "qiskit.algorithms.eigen_solvers.eigen_solver.EigensolverResult") + +Deprecated: VQD Result. + +The VQDResult class has been superseded by the [`qiskit.algorithms.eigensolvers.VQDResult`](qiskit.algorithms.eigensolvers.VQDResult "qiskit.algorithms.eigensolvers.VQDResult") class. This class will be deprecated in a future release and subsequently removed after that. + + + The class `qiskit.algorithms.eigen_solvers.vqd.VQDResult` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.eigensolvers.VQDResult`.See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +## Attributes + + + +### aux\_operator\_eigenvalues + +Return aux operator expectation values. + +These values are in fact tuples formatted as (mean, standard deviation). + + + +### cost\_function\_evals + +Returns number of cost optimizer evaluations + + + +### eigenstates + +return eigen state + + + +### eigenvalues + +returns eigen values + + + +### optimal\_circuit + +The optimal circuits. Along with the optimal parameters, these can be used to retrieve the minimum eigenstate. + + + +### optimal\_parameters + +Returns the optimal parameters in a dictionary + + + +### optimal\_point + +Returns optimal point + + + +### optimal\_value + +Returns optimal value + + + +### optimizer\_evals + +Returns number of optimizer evaluations + + + +### optimizer\_result + +Returns the optimizer result + + + +### optimizer\_time + +Returns time taken for optimization + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.VQE.md b/docs/api/qiskit/0.46/qiskit.algorithms.VQE.md new file mode 100644 index 00000000000..d021ddd4811 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.VQE.md @@ -0,0 +1,270 @@ +--- +title: VQE +description: API reference for qiskit.algorithms.VQE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.VQE +--- + +# VQE + + + +`qiskit.algorithms.VQE(ansatz=None, optimizer=None, initial_point=None, gradient=None, expectation=None, include_custom=False, max_evals_grouped=1, callback=None, quantum_instance=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigen_solvers/vqe.py "view source code") + +Bases: `VariationalAlgorithm`, [`MinimumEigensolver`](qiskit.algorithms.MinimumEigensolver "qiskit.algorithms.minimum_eigen_solvers.minimum_eigen_solver.MinimumEigensolver") + +Deprecated: Variational Quantum Eigensolver algorithm. + +The VQE class has been superseded by the [`qiskit.algorithms.minimum_eigensolvers.VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE") class. This class will be deprecated in a future release and subsequently removed after that. + +[VQE](https://arxiv.org/abs/1304.3061) is a quantum algorithm that uses a variational technique to find the minimum eigenvalue of the Hamiltonian $H$ of a given system. + +An instance of VQE requires defining two algorithmic sub-components: a trial state (a.k.a. ansatz) which is a `QuantumCircuit`, and one of the classical [`optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers"). The ansatz is varied, via its set of parameters, by the optimizer, such that it works towards a state, as determined by the parameters applied to the ansatz, that will result in the minimum expectation value being measured of the input operator (Hamiltonian). + +An optional array of parameter values, via the *initial\_point*, may be provided as the starting point for the search of the minimum eigenvalue. This feature is particularly useful such as when there are reasons to believe that the solution point is close to a particular point. As an example, when building the dissociation profile of a molecule, it is likely that using the previous computed optimal solution as the starting initial point for the next interatomic distance is going to reduce the number of iterations necessary for the variational algorithm to converge. It provides an [initial point tutorial](https://github.com/Qiskit/qiskit-tutorials-community/blob/master/chemistry/h2_vqe_initial_point.ipynb) detailing this use case. + +The length of the *initial\_point* list value must match the number of the parameters expected by the ansatz being used. If the *initial\_point* is left at the default of `None`, then VQE will look to the ansatz for a preferred value, based on its given initial state. If the ansatz returns `None`, then a random point will be generated within the parameter bounds set, as per above. If the ansatz provides `None` as the lower bound, then VQE will default it to $-2\pi$; similarly, if the ansatz returns `None` as the upper bound, the default value will be $2\pi$. + +The optimizer can either be one of Qiskit’s optimizers, such as [`SPSA`](qiskit.algorithms.optimizers.SPSA "qiskit.algorithms.optimizers.SPSA") or a callable with the following signature: + + + The callable \_must\_ have the argument names `fun, x0, jac, bounds` as indicated in the following code block. + + +```python +from qiskit.algorithms.optimizers import OptimizerResult + +def my_minimizer(fun, x0, jac=None, bounds=None) -> OptimizerResult: + # Note that the callable *must* have these argument names! + # Args: + # fun (callable): the function to minimize + # x0 (np.ndarray): the initial point for the optimization + # jac (callable, optional): the gradient of the objective function + # bounds (list, optional): a list of tuples specifying the parameter bounds + + result = OptimizerResult() + result.x = # optimal parameters + result.fun = # optimal function value + return result +``` + +The above signature also allows to directly pass any SciPy minimizer, for instance as + +```python +from functools import partial +from scipy.optimize import minimize + +optimizer = partial(minimize, method="L-BFGS-B") +``` + + + The class `qiskit.algorithms.minimum_eigen_solvers.vqe.VQE` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. Instead, use the class `qiskit.algorithms.minimum_eigensolvers.VQE`. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A parameterized circuit used as Ansatz for the wave function. +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") *| None*) – A classical optimizer. Can either be a Qiskit optimizer or a callable that takes an array as input and returns a Qiskit or SciPy optimization result. +* **initial\_point** (*np.ndarray | None*) – An optional initial point (i.e. initial parameter values) for the optimizer. If `None` then VQE will look to the ansatz for a preferred point and if not will simply compute a random one. +* **gradient** ([*GradientBase*](qiskit.opflow.gradients.GradientBase "qiskit.opflow.gradients.GradientBase") *| Callable | None*) – An optional gradient function or operator for optimizer. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase") *| None*) – The Expectation converter for taking the average value of the Observable over the ansatz state function. When `None` (the default) an [`ExpectationFactory`](qiskit.opflow.expectations.ExpectationFactory "qiskit.opflow.expectations.ExpectationFactory") is used to select an appropriate expectation based on the operator and backend. When using Aer qasm\_simulator backend, with paulis, it is however much faster to leverage custom Aer function for the computation but, although VQE performs much faster with it, the outcome is ideal, with no shot noise, like using a state vector simulator. If you are just looking for the quickest performance when choosing Aer qasm\_simulator and the lack of shot noise is not an issue then set include\_custom parameter here to `True` (defaults to `False`). +* **include\_custom** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When expectation parameter here is None setting this to `True` will allow the factory to include the custom Aer pauli expectation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of evaluations performed simultaneously. Signals the given optimizer that more than one set of parameters can be supplied so that potentially the expectation values can be computed in parallel. Typically this is possible when a finite difference gradient is used by the optimizer such that multiple points to compute the gradient can be passed and if computed in parallel improve overall execution time. Deprecated if a gradient operator or function is given. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*], None] | None*) – a callback that can access the intermediate data during the optimization. Four parameter values are passed to the callback as follows during each evaluation by the optimizer for its current set of parameters as it works towards the minimum. These are: the evaluation count, the optimizer parameters for the ansatz, the evaluated mean and the evaluated standard deviation.\` +* **quantum\_instance** ([*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *|*[*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *| None*) – Quantum Instance or Backend + +## Attributes + + + +### ansatz + +Returns the ansatz. + + + +### callback + +Returns callback + + + +### expectation + +The expectation value algorithm used to construct the expectation measurement from the observable. + + + +### gradient + +Returns the gradient. + + + +### include\_custom + +Returns include\_custom + + + +### initial\_point + +Returns initial point + + + +### max\_evals\_grouped + +Returns max\_evals\_grouped + + + +### optimizer + +Returns optimizer + + + +### quantum\_instance + +Returns quantum instance. + + + +### setting + +Prepare the setting of VQE as a string. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes minimum eigenvalue. Operator and aux\_operators can be supplied here and if not None will override any already set into algorithm so it can be reused with different operators. While an operator is required by algorithms, aux\_operators are optional. To ‘remove’ a previous aux\_operators array use an empty list here. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **aux\_operators** (*ListOrDict\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators, total particle count operators so we can get values for these at the ground state. + +**Returns** + +MinimumEigensolverResult + +**Return type** + +[MinimumEigensolverResult](qiskit.algorithms.MinimumEigensolverResult "qiskit.algorithms.MinimumEigensolverResult") + +### construct\_circuit + + + +`construct_circuit(parameter, operator)` + +Return the circuits used to compute the expectation value. + +**Parameters** + +* **parameter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | np.ndarray*) – Parameters for the ansatz circuit. +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable + +**Returns** + +A list of the circuits used to compute the expectation value. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")] + +### construct\_expectation + + + +`construct_expectation(parameter, operator, return_expectation=False)` + +Generate the ansatz circuit and expectation value measurement, and return their runnable composition. + +**Parameters** + +* **parameter** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | np.ndarray*) – Parameters for the ansatz circuit. +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – Qubit operator of the Observable +* **return\_expectation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, return the `ExpectationBase` expectation converter used in the construction of the expectation value. Useful e.g. to compute the standard deviation of the expectation value. + +**Returns** + +The Operator equalling the measurement of the ansatz `StateFn` by the Observable’s expectation `StateFn`, and, optionally, the expectation converter. + +**Raises** + +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If no operator has been provided. +* [**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If no expectation is passed and None could be inferred via the ExpectationFactory. + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase"), [ExpectationBase](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")] + +### get\_energy\_evaluation + + + +`get_energy_evaluation(operator, return_expectation=False)` + +Returns a function handle to evaluates the energy at given parameters for the ansatz. + +This is the objective function to be passed to the optimizer that is used for evaluation. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")) – The operator whose energy to evaluate. +* **return\_expectation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, return the `ExpectationBase` expectation converter used in the construction of the expectation value. Useful e.g. to evaluate other operators with the same expectation value converter. + +**Returns** + +Energy of the hamiltonian of each parameter, and, optionally, the expectation converter. + +**Raises** + +[**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.12)") – If the circuit is not parameterized (i.e. has 0 free parameters). + +**Return type** + +Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[Callable\[\[np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]], [ExpectationBase](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")] + +### print\_settings + + + +`print_settings()` + +Preparing the setting of VQE into a string. + +**Returns** + +the formatted setting of VQE + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.VarQITE.md b/docs/api/qiskit/0.46/qiskit.algorithms.VarQITE.md new file mode 100644 index 00000000000..811c71c96c2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.VarQITE.md @@ -0,0 +1,56 @@ +--- +title: VarQITE +description: API reference for qiskit.algorithms.VarQITE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.VarQITE +--- + +# VarQITE + + + +`qiskit.algorithms.VarQITE(ansatz, initial_parameters, variational_principle=None, estimator=None, ode_solver=, lse_solver=None, num_timesteps=None, imag_part_tol=1e-07, num_instability_tol=1e-07)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/var_qite.py "view source code") + +Bases: `VarQTE`, [`ImaginaryTimeEvolver`](qiskit.algorithms.ImaginaryTimeEvolver "qiskit.algorithms.time_evolvers.imaginary_time_evolver.ImaginaryTimeEvolver") + +Variational Quantum Imaginary Time Evolution algorithm. + +**Parameters** + +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Ansatz to be used for variational time evolution. +* **initial\_parameters** (*Mapping\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Initial parameter values for the ansatz. +* **variational\_principle** ([*ImaginaryVariationalPrinciple*](qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple "qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple") *| None*) – Variational Principle to be used. Defaults to `ImaginaryMcLachlanPrinciple`. +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") *| None*) – An estimator primitive used for calculating expectation values of TimeEvolutionProblem.aux\_operators. +* **ode\_solver** ([*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")*\[OdeSolver] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – ODE solver callable that implements a SciPy `OdeSolver` interface or a string indicating a valid method offered by SciPy. +* **lse\_solver** (*Callable\[\[np.ndarray, np.ndarray], np.ndarray] | None*) – Linear system of equations solver callable. It accepts `A` and `b` to solve `Ax=b` and returns `x`. If `None`, the default `np.linalg.lstsq` solver is used. +* **num\_timesteps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of timesteps to take. If `None`, it is automatically selected to achieve a timestep of approximately 0.01. Only relevant in case of the `ForwardEulerSolver`. +* **imag\_part\_tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Allowed value of an imaginary part that can be neglected if no imaginary part is expected. +* **num\_instability\_tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The amount of negative value that is allowed to be rounded up to 0 for quantities that are expected to be non-negative. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Apply Variational Quantum Time Evolution to the given operator. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – Instance defining an evolution problem. + +**Returns** + +Result of the evolution which includes a quantum circuit with bound parameters as an evolved state and, if provided, observables evaluated on the evolved state. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `initial_state` is included in the `evolution_problem`. + +**Return type** + +*VarQTEResult* + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.VarQRTE.md b/docs/api/qiskit/0.46/qiskit.algorithms.VarQRTE.md new file mode 100644 index 00000000000..7f82404a884 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.VarQRTE.md @@ -0,0 +1,56 @@ +--- +title: VarQRTE +description: API reference for qiskit.algorithms.VarQRTE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.VarQRTE +--- + +# VarQRTE + + + +`qiskit.algorithms.VarQRTE(ansatz, initial_parameters, variational_principle=None, estimator=None, ode_solver=, lse_solver=None, num_timesteps=None, imag_part_tol=1e-07, num_instability_tol=1e-07)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/var_qrte.py "view source code") + +Bases: `VarQTE`, [`RealTimeEvolver`](qiskit.algorithms.RealTimeEvolver "qiskit.algorithms.time_evolvers.real_time_evolver.RealTimeEvolver") + +Variational Quantum Real Time Evolution algorithm. + +**Parameters** + +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Ansatz to be used for variational time evolution. +* **initial\_parameters** (*Mapping\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Initial parameter values for an ansatz. +* **variational\_principle** ([*RealVariationalPrinciple*](qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple "qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple") *| None*) – Variational Principle to be used. Defaults to `RealMcLachlanPrinciple`. +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") *| None*) – An estimator primitive used for calculating expectation values of TimeEvolutionProblem.aux\_operators. +* **ode\_solver** ([*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")*\[OdeSolver] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – ODE solver callable that implements a SciPy `OdeSolver` interface or a string indicating a valid method offered by SciPy. +* **lse\_solver** (*Callable\[\[np.ndarray, np.ndarray], np.ndarray] | None*) – Linear system of equations solver callable. It accepts `A` and `b` to solve `Ax=b` and returns `x`. If `None`, the default `np.linalg.lstsq` solver is used. +* **num\_timesteps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of timesteps to take. If `None`, it is automatically selected to achieve a timestep of approximately 0.01. Only relevant in case of the `ForwardEulerSolver`. +* **imag\_part\_tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Allowed value of an imaginary part that can be neglected if no imaginary part is expected. +* **num\_instability\_tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The amount of negative value that is allowed to be rounded up to 0 for quantities that are expected to be non-negative. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Apply Variational Quantum Time Evolution to the given operator. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – Instance defining an evolution problem. + +**Returns** + +Result of the evolution which includes a quantum circuit with bound parameters as an evolved state and, if provided, observables evaluated on the evolved state. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `initial_state` is included in the `evolution_problem`. + +**Return type** + +*VarQTEResult* + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.Eigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.Eigensolver.md new file mode 100644 index 00000000000..d5b2ed3ab00 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.Eigensolver.md @@ -0,0 +1,61 @@ +--- +title: Eigensolver +description: API reference for qiskit.algorithms.eigensolvers.Eigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.eigensolvers.Eigensolver +--- + +# Eigensolver + + + +`qiskit.algorithms.eigensolvers.Eigensolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigensolvers/eigensolver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +The eigensolver interface. + +Algorithms that can compute eigenvalues for an operator may implement this interface to allow different algorithms to be used interchangeably. + +## Methods + +### compute\_eigenvalues + + + +`abstract compute_eigenvalues(operator, aux_operators=None)` + +Computes the minimum eigenvalue. The `operator` and `aux_operators` are supplied here. While an `operator` is required by algorithms, `aux_operators` are optional. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Qubit operator of the observable. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance, in chemistry, these can be dipole operators and total particle count operators, so we can get values for these at the ground state. + +**Returns** + +An eigensolver result. + +**Return type** + +[EigensolverResult](qiskit.algorithms.eigensolvers.EigensolverResult "qiskit.algorithms.eigensolvers.EigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the eigensolver computes the eigenvalues of the main operator, then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +`True` if `aux_operator` expectations can be evaluated, `False` otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.EigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.EigensolverResult.md new file mode 100644 index 00000000000..c1264ba5c4d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.EigensolverResult.md @@ -0,0 +1,48 @@ +--- +title: EigensolverResult +description: API reference for qiskit.algorithms.eigensolvers.EigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.eigensolvers.EigensolverResult +--- + +# EigensolverResult + + + +`qiskit.algorithms.eigensolvers.EigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigensolvers/eigensolver.py "view source code") + +Bases: `AlgorithmResult` + +Eigensolver result. + +## Attributes + + + +### aux\_operators\_evaluated + +Return the aux operator expectation values. + +These values are in fact tuples formatted as (mean, metadata). + + + +### eigenvalues + +Return the eigenvalues. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolver.md new file mode 100644 index 00000000000..f3b0e4a0977 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolver.md @@ -0,0 +1,84 @@ +--- +title: NumPyEigensolver +description: API reference for qiskit.algorithms.eigensolvers.NumPyEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.eigensolvers.NumPyEigensolver +--- + +# NumPyEigensolver + + + +`qiskit.algorithms.eigensolvers.NumPyEigensolver(k=1, filter_criterion=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigensolvers/numpy_eigensolver.py "view source code") + +Bases: [`Eigensolver`](qiskit.algorithms.eigensolvers.Eigensolver "qiskit.algorithms.eigensolvers.eigensolver.Eigensolver") + +The NumPy eigensolver algorithm. + +The NumPy Eigensolver computes up to the first $k$ eigenvalues of a complex-valued square matrix of dimension $n \times n$, with $k \leq n$. + + + Operators are automatically converted to SciPy’s `spmatrix` as needed and this conversion can be costly in terms of memory and performance as the operator size, mostly in terms of number of qubits it represents, gets larger. + + +**Parameters** + +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of eigenvalues are to be computed, with a minimum value of 1. +* **filter\_criterion** (*FilterType | None*) – Callable that allows to filter eigenvalues/eigenstates. Only feasible eigenstates are returned in the results. The callable has the signature `filter(eigenstate, eigenvalue, aux_values)` and must return a boolean to indicate whether to keep this value in the final returned result or not. If the number of elements that satisfies the criterion is smaller than `k`, then the returned list will have fewer elements and can even be empty. + +## Attributes + + + +### filter\_criterion + +Return the filter criterion if set. + + + +### k + +Return k (number of eigenvalues requested). + +## Methods + +### compute\_eigenvalues + + + +`compute_eigenvalues(operator, aux_operators=None)` + +Computes the minimum eigenvalue. The `operator` and `aux_operators` are supplied here. While an `operator` is required by algorithms, `aux_operators` are optional. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Qubit operator of the observable. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance, in chemistry, these can be dipole operators and total particle count operators, so we can get values for these at the ground state. + +**Returns** + +An eigensolver result. + +**Return type** + +[NumPyEigensolverResult](qiskit.algorithms.eigensolvers.NumPyEigensolverResult "qiskit.algorithms.eigensolvers.NumPyEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the eigensolver computes the eigenvalues of the main operator, then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +`True` if `aux_operator` expectations can be evaluated, `False` otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolverResult.md new file mode 100644 index 00000000000..2a492983aa9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.NumPyEigensolverResult.md @@ -0,0 +1,54 @@ +--- +title: NumPyEigensolverResult +description: API reference for qiskit.algorithms.eigensolvers.NumPyEigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.eigensolvers.NumPyEigensolverResult +--- + +# NumPyEigensolverResult + + + +`qiskit.algorithms.eigensolvers.NumPyEigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigensolvers/numpy_eigensolver.py "view source code") + +Bases: [`EigensolverResult`](qiskit.algorithms.eigensolvers.EigensolverResult "qiskit.algorithms.eigensolvers.eigensolver.EigensolverResult") + +NumPy eigensolver result. + +## Attributes + + + +### aux\_operators\_evaluated + +Return the aux operator expectation values. + +These values are in fact tuples formatted as (mean, metadata). + + + +### eigenstates + +Return eigenstates. + + + +### eigenvalues + +Return the eigenvalues. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQD.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQD.md new file mode 100644 index 00000000000..aa9f706b38c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQD.md @@ -0,0 +1,173 @@ +--- +title: VQD +description: API reference for qiskit.algorithms.eigensolvers.VQD +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.eigensolvers.VQD +--- + +# VQD + + + +`qiskit.algorithms.eigensolvers.VQD(estimator, fidelity, ansatz, optimizer, *, k=2, betas=None, initial_point=None, callback=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigensolvers/vqd.py "view source code") + +Bases: `VariationalAlgorithm`, [`Eigensolver`](qiskit.algorithms.eigensolvers.Eigensolver "qiskit.algorithms.eigensolvers.eigensolver.Eigensolver") + +The Variational Quantum Deflation algorithm. Implementation using primitives. + +[VQD](https://arxiv.org/abs/1805.08138) is a quantum algorithm that uses a variational technique to find the k eigenvalues of the Hamiltonian $H$ of a given system. + +The algorithm computes excited state energies of generalised hamiltonians by optimising over a modified cost function where each succesive eigenvalue is calculated iteratively by introducing an overlap term with all the previously computed eigenstates that must be minimised, thus ensuring higher energy eigenstates are found. + +An instance of VQD requires defining three algorithmic sub-components: an integer k denoting the number of eigenstates to calculate, a trial state (a.k.a. ansatz) which is a `QuantumCircuit`, and one instance (or list of) classical [`optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers"). The optimizer varies the circuit parameters The trial state $|\psi(\vec\theta)\rangle$ is varied by the optimizer, which modifies the set of ansatz parameters $\vec\theta$ such that the expectation value of the operator on the corresponding state approaches a minimum. The algorithm does this by iteratively refining each excited state to be orthogonal to all the previous excited states. + +An optional array of parameter values, via the *initial\_point*, may be provided as the starting point for the search of the minimum eigenvalue. This feature is particularly useful when there are reasons to believe that the solution point is close to a particular point. + +The length of the *initial\_point* list value must match the number of the parameters expected by the ansatz. If the *initial\_point* is left at the default of `None`, then VQD will look to the ansatz for a preferred value, based on its given initial state. If the ansatz returns `None`, then a random point will be generated within the parameter bounds set, as per above. It is also possible to give a list of initial points, one for every kth eigenvalue. If the ansatz provides `None` as the lower bound, then VQD will default it to $-2\pi$; similarly, if the ansatz returns `None` as the upper bound, the default value will be $2\pi$. + +The following attributes can be set via the initializer but can also be read and updated once the VQD object has been constructed. + + + +### estimator + +The primitive instance used to perform the expectation estimation as indicated in the VQD paper. + +**Type** + +[BaseEstimator](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") + + + +### fidelity + +The fidelity class instance used to compute the overlap estimation as indicated in the VQD paper. + +**Type** + +[BaseStateFidelity](qiskit.algorithms.state_fidelities.BaseStateFidelity "qiskit.algorithms.state_fidelities.BaseStateFidelity") + + + +### ansatz + +A parameterized circuit used as ansatz for the wave function. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + + + +### optimizer + +A classical optimizer or a list of optimizers, + +**Type** + +[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") | Sequence\[[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer")] + +### one for every k-th eigenvalue. Can either be a Qiskit optimizer or a callable + +that takes an array as input and returns a Qiskit or SciPy optimization result. + + + +### k + +the number of eigenvalues to return. Returns the lowest k eigenvalues. + +**Type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### betas + +Beta parameters in the VQD paper. Should have length k - 1, with k the number of excited states. These hyper-parameters balance the contribution of each overlap term to the cost function and have a default value computed as the mean square sum of the coefficients of the observable. + +**Type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### initial point + +An optional initial point (i.e. initial parameter values) or a list of initial points (one for every k-th eigenvalue) for the optimizer. If `None` then VQD will look to the ansatz for a preferred point and if not will simply compute a random one. + +**Type** + +Sequence\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] | Sequence\[Sequence\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] | None + + + +### callback + +A callback that can access the intermediate data during the optimization. Four parameter values are passed to the callback as follows during each evaluation by the optimizer: the evaluation count, the optimizer parameters for the ansatz, the estimated value, the estimation metadata, and the current step. + +**Type** + +Callable\[\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), np.ndarray, [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), Any]], None] | None + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator primitive. +* **fidelity** ([*BaseStateFidelity*](qiskit.algorithms.state_fidelities.BaseStateFidelity "qiskit.algorithms.state_fidelities.BaseStateFidelity")) – The fidelity class using primitives. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A parameterized circuit used as ansatz for the wave function. +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") *| Sequence\[*[*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer")*]*) – A classical optimizer or a list of optimizers, one for every k-th eigenvalue. +* **callable** (*Can either be a Qiskit optimizer or a*) – that takes an array as input and returns a Qiskit or SciPy optimization result. +* **k** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of eigenvalues to return. Returns the lowest k eigenvalues. +* **betas** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Beta parameters in the VQD paper. Should have length k - 1, with k the number of excited states. These hyperparameters balance the contribution of each overlap term to the cost function and have a default value computed as the mean square sum of the coefficients of the observable. +* **initial\_point** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – An optional initial point (i.e. initial parameter values) or a list of initial points (one for every k-th eigenvalue) for the optimizer. If `None` then VQD will look to the ansatz for a preferred point and if not will simply compute a random one. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any]], None] | None*) – A callback that can access the intermediate data during the optimization. Four parameter values are passed to the callback as follows during each evaluation by the optimizer: the evaluation count, the optimizer parameters for the ansatz, the estimated value, the estimation metadata, and the current step. + +## Attributes + + + +### initial\_point + +Returns initial point. + +## Methods + +### compute\_eigenvalues + + + +`compute_eigenvalues(operator, aux_operators=None)` + +Computes the minimum eigenvalue. The `operator` and `aux_operators` are supplied here. While an `operator` is required by algorithms, `aux_operators` are optional. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Qubit operator of the observable. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the eigenstate of the minimum eigenvalue main result and their expectation values returned. For instance, in chemistry, these can be dipole operators and total particle count operators, so we can get values for these at the ground state. + +**Returns** + +An eigensolver result. + +**Return type** + +[VQDResult](qiskit.algorithms.eigensolvers.VQDResult "qiskit.algorithms.eigensolvers.VQDResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the eigensolver computes the eigenvalues of the main operator, then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +`True` if `aux_operator` expectations can be evaluated, `False` otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQDResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQDResult.md new file mode 100644 index 00000000000..58c1ff70950 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.VQDResult.md @@ -0,0 +1,90 @@ +--- +title: VQDResult +description: API reference for qiskit.algorithms.eigensolvers.VQDResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.eigensolvers.VQDResult +--- + +# VQDResult + + + +`qiskit.algorithms.eigensolvers.VQDResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/eigensolvers/vqd.py "view source code") + +Bases: [`EigensolverResult`](qiskit.algorithms.eigensolvers.EigensolverResult "qiskit.algorithms.eigensolvers.eigensolver.EigensolverResult") + +VQD Result. + +## Attributes + + + +### aux\_operators\_evaluated + +Return the aux operator expectation values. + +These values are in fact tuples formatted as (mean, metadata). + + + +### cost\_function\_evals + +Returns number of cost optimizer evaluations + + + +### eigenvalues + +Return the eigenvalues. + + + +### optimal\_circuits + +The optimal circuits. Along with the optimal parameters, these can be used to retrieve the different eigenstates. + + + +### optimal\_parameters + +Returns the optimal parameters for each step + + + +### optimal\_points + +Returns optimal point for each step + + + +### optimal\_values + +Returns optimal value for each step + + + +### optimizer\_results + +Returns the optimizer results for each step + + + +### optimizer\_times + +Returns time taken for optimization for each step + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.md b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.md new file mode 100644 index 00000000000..a1fac22f05f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.eigensolvers.md @@ -0,0 +1,38 @@ +--- +title: eigensolvers +description: API reference for qiskit.algorithms.eigensolvers +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.eigensolvers +--- + + + + + +# qiskit.algorithms.eigensolvers + + + +## Eigensolvers Package + + + +`qiskit.algorithms.eigensolvers` + +### Eigensolvers + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | +| [`Eigensolver`](qiskit.algorithms.eigensolvers.Eigensolver "qiskit.algorithms.eigensolvers.Eigensolver")() | The eigensolver interface. | +| [`NumPyEigensolver`](qiskit.algorithms.eigensolvers.NumPyEigensolver "qiskit.algorithms.eigensolvers.NumPyEigensolver")(\[k, filter\_criterion]) | The NumPy eigensolver algorithm. | +| [`VQD`](qiskit.algorithms.eigensolvers.VQD "qiskit.algorithms.eigensolvers.VQD")(estimator, fidelity, ansatz, optimizer, \*) | The Variational Quantum Deflation algorithm. | + +### Results + +> | | | +> | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +> | [`EigensolverResult`](qiskit.algorithms.eigensolvers.EigensolverResult "qiskit.algorithms.eigensolvers.EigensolverResult")() | Eigensolver result. | +> | [`NumPyEigensolverResult`](qiskit.algorithms.eigensolvers.NumPyEigensolverResult "qiskit.algorithms.eigensolvers.NumPyEigensolverResult")() | NumPy eigensolver result. | +> | [`VQDResult`](qiskit.algorithms.eigensolvers.VQDResult "qiskit.algorithms.eigensolvers.VQDResult")() | VQD Result. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseEstimatorGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseEstimatorGradient.md new file mode 100644 index 00000000000..9e6baec477b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseEstimatorGradient.md @@ -0,0 +1,98 @@ +--- +title: BaseEstimatorGradient +description: API reference for qiskit.algorithms.gradients.BaseEstimatorGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.BaseEstimatorGradient +--- + +# BaseEstimatorGradient + + + +`qiskit.algorithms.gradients.BaseEstimatorGradient(estimator, options=None, derivative_type=DerivativeType.REAL)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/base/base_estimator_gradient.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for an `EstimatorGradient` to compute the gradients of the expectation value. + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the gradients. + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +* **derivative\_type** (*DerivativeType*) – + + The type of derivative. Can be either `DerivativeType.REAL` `DerivativeType.IMAG`, or `DerivativeType.COMPLEX`. + + > * `DerivativeType.REAL` computes $2 \mathrm{Re}[⟨ψ(ω)|O(θ)|dω ψ(ω)〉]$. + > * `DerivativeType.IMAG` computes $2 \mathrm{Im}[⟨ψ(ω)|O(θ)|dω ψ(ω)〉]$. + > * `DerivativeType.COMPLEX` computes $2 ⟨ψ(ω)|O(θ)|dω ψ(ω)〉$. + + Defaults to `DerivativeType.REAL`, as this yields e.g. the commonly-used energy gradient and this type is the only supported type for function-level schemes like finite difference. + +## Attributes + + + +### derivative\_type + +Return the derivative type (real, imaginary or complex). + +**Returns** + +The derivative type. + + + +### options + +Return the union of estimator options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + estimator options. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values, parameters=None, **options)` + +Run the job of the estimator gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – The list of observables. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th element of the i-th result corresponds to the gradient of the i-th circuit with respect to the j-th parameter. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseQGT.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseQGT.md new file mode 100644 index 00000000000..8e24e88cd72 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseQGT.md @@ -0,0 +1,115 @@ +--- +title: BaseQGT +description: API reference for qiskit.algorithms.gradients.BaseQGT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.BaseQGT +--- + +# BaseQGT + + + +`qiskit.algorithms.gradients.BaseQGT(estimator, phase_fix=True, derivative_type=DerivativeType.COMPLEX, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/base/base_qgt.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class to computes the Quantum Geometric Tensor (QGT) given a pure, parameterized quantum state. QGT is defined as: + +$$ +\mathrm{QGT}_{ij}= \langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle. +$$ + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the QGT. + +* **phase\_fix** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to calculate the second term (phase fix) of the QGT, which is $\langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle$. Defaults to `True`. + +* **derivative\_type** (*DerivativeType*) – + + The type of derivative. Can be either `DerivativeType.REAL` `DerivativeType.IMAG`, or `DerivativeType.COMPLEX`. Defaults to `DerivativeType.REAL`. + + * `DerivativeType.REAL` computes + + $$ + \mathrm{Re(QGT)}_{ij}= \mathrm{Re}[\langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. + $$ + + * `DerivativeType.IMAG` computes + + $$ + \mathrm{Im(QGT)}_{ij}= \mathrm{Im}[\langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. + $$ + + * `DerivativeType.COMPLEX` computes + + $$ + \mathrm{QGT}_{ij}= [\langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. + $$ + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Backend runtime options used for circuit execution. The order of priority is: options in `run` method > QGT’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +## Attributes + + + +### derivative\_type + +The derivative type. + + + +### options + +Return the union of estimator options setting and QGT default options, where, if the same field is set in both, the QGT’s default options override the primitive’s default setting. + +**Returns** + +The QGT default + estimator options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the QGTs on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the QGTs. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the QGTs of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the QGTs of all parameters in each circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > QGT’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +**Returns** + +The job object of the QGTs of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseSamplerGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseSamplerGradient.md new file mode 100644 index 00000000000..ea964ae2633 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.BaseSamplerGradient.md @@ -0,0 +1,76 @@ +--- +title: BaseSamplerGradient +description: API reference for qiskit.algorithms.gradients.BaseSamplerGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.BaseSamplerGradient +--- + +# BaseSamplerGradient + + + +`qiskit.algorithms.gradients.BaseSamplerGradient(sampler, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/base/base_sampler_gradient.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for a `SamplerGradient` to compute the gradients of the sampling probability. + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler used to compute the gradients. +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +## Attributes + + + +### options + +Return the union of sampler options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + sampler options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the sampler gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the sampling probability. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th quasi-probability distribution in the i-th result corresponds to the gradients of the sampling probability for the j-th parameter in `circuits[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.EstimatorGradientResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.EstimatorGradientResult.md new file mode 100644 index 00000000000..c9f73e02483 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.EstimatorGradientResult.md @@ -0,0 +1,44 @@ +--- +title: EstimatorGradientResult +description: API reference for qiskit.algorithms.gradients.EstimatorGradientResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.EstimatorGradientResult +--- + +# EstimatorGradientResult + + + +`qiskit.algorithms.gradients.EstimatorGradientResult(gradients, metadata, options)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/base/estimator_gradient_result.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Result of EstimatorGradient. + +## Attributes + + + +### gradients + +`list[numpy.ndarray]` + +The gradients of the expectation values. + + + +### metadata + +`list[dict[str, Any]]` + +Additional information about the job. + + + +### options + +`Options` + +Primitive runtime options for the execution of the job. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffEstimatorGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffEstimatorGradient.md new file mode 100644 index 00000000000..6ce94f07798 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffEstimatorGradient.md @@ -0,0 +1,107 @@ +--- +title: FiniteDiffEstimatorGradient +description: API reference for qiskit.algorithms.gradients.FiniteDiffEstimatorGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.FiniteDiffEstimatorGradient +--- + +# FiniteDiffEstimatorGradient + + + +`qiskit.algorithms.gradients.FiniteDiffEstimatorGradient(estimator, epsilon, options=None, *, method='central')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/finite_diff/finite_diff_estimator_gradient.py "view source code") + +Bases: [`BaseEstimatorGradient`](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.base.base_estimator_gradient.BaseEstimatorGradient") + +Compute the gradients of the expectation values by finite difference method \[1]. + +**Reference:** \[1] [Finite difference method](https://en.wikipedia.org/wiki/Finite_difference_method) + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the gradients. + +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The offset size for the finite difference gradients. + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +* **method** (*Literal\['central', 'forward', 'backward']*) – + + The computation method of the gradients. + + > * `central` computes $\frac{f(x+e)-f(x-e)}{2e}$, + > * `forward` computes $\frac{f(x+e) - f(x)}{e}$, + > * `backward` computes $\frac{f(x)-f(x-e)}{e}$ + + where $e$ is epsilon. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `epsilon` is not positive. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `method` is invalid. + +## Attributes + + + +### derivative\_type + +Return the derivative type (real, imaginary or complex). + +**Returns** + +The derivative type. + + + +### options + +Return the union of estimator options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + estimator options. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values, parameters=None, **options)` + +Run the job of the estimator gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – The list of observables. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th element of the i-th result corresponds to the gradient of the i-th circuit with respect to the j-th parameter. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffSamplerGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffSamplerGradient.md new file mode 100644 index 00000000000..13d46349162 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.FiniteDiffSamplerGradient.md @@ -0,0 +1,96 @@ +--- +title: FiniteDiffSamplerGradient +description: API reference for qiskit.algorithms.gradients.FiniteDiffSamplerGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.FiniteDiffSamplerGradient +--- + +# FiniteDiffSamplerGradient + + + +`qiskit.algorithms.gradients.FiniteDiffSamplerGradient(sampler, epsilon, options=None, *, method='central')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/finite_diff/finite_diff_sampler_gradient.py "view source code") + +Bases: [`BaseSamplerGradient`](qiskit.algorithms.gradients.BaseSamplerGradient "qiskit.algorithms.gradients.base.base_sampler_gradient.BaseSamplerGradient") + +Compute the gradients of the sampling probability by finite difference method \[1]. + +**Reference:** \[1] [Finite difference method](https://en.wikipedia.org/wiki/Finite_difference_method) + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler used to compute the gradients. + +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The offset size for the finite difference gradients. + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +* **method** (*Literal\['central', 'forward', 'backward']*) – + + The computation method of the gradients. + + > * `central` computes $\frac{f(x+e)-f(x-e)}{2e}$, + > * `forward` computes $\frac{f(x+e) - f(x)}{e}$, + > * `backward` computes $\frac{f(x)-f(x-e)}{e}$ + + where $e$ is epsilon. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `epsilon` is not positive. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `method` is invalid. + +## Attributes + + + +### options + +Return the union of sampler options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + sampler options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the sampler gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the sampling probability. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th quasi-probability distribution in the i-th result corresponds to the gradients of the sampling probability for the j-th parameter in `circuits[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombEstimatorGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombEstimatorGradient.md new file mode 100644 index 00000000000..ddb39859b71 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombEstimatorGradient.md @@ -0,0 +1,104 @@ +--- +title: LinCombEstimatorGradient +description: API reference for qiskit.algorithms.gradients.LinCombEstimatorGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.LinCombEstimatorGradient +--- + +# LinCombEstimatorGradient + + + +`qiskit.algorithms.gradients.LinCombEstimatorGradient(estimator, derivative_type=DerivativeType.REAL, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/lin_comb/lin_comb_estimator_gradient.py "view source code") + +Bases: [`BaseEstimatorGradient`](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.base.base_estimator_gradient.BaseEstimatorGradient") + +Compute the gradients of the expectation values. This method employs a linear combination of unitaries \[1]. + +**Reference:** \[1] Schuld et al., Evaluating analytic gradients on quantum hardware, 2018 [arXiv:1811.11184](https://arxiv.org/pdf/1811.11184.pdf) + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the gradients. + +* **derivative\_type** (*DerivativeType*) – + + The type of derivative. Can be either `DerivativeType.REAL` `DerivativeType.IMAG`, or `DerivativeType.COMPLEX`. Defaults to `DerivativeType.REAL`. + + > * `DerivativeType.REAL` computes $2 \mathrm{Re}[⟨ψ(ω)|O(θ)|dω ψ(ω)〉]$. + > * `DerivativeType.IMAG` computes $2 \mathrm{Im}[⟨ψ(ω)|O(θ)|dω ψ(ω)〉]$. + > * `DerivativeType.COMPLEX` computes $2 ⟨ψ(ω)|O(θ)|dω ψ(ω)〉$. + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['rx', 'ry', 'rz', 'rzx', 'rzz', 'ryy', 'rxx', 'cx', 'cy', 'cz', 'ccx', 'swap', 'iswap', 'h', 't', 's', 'sdg', 'x', 'y', 'z']` + + + +### derivative\_type + +Return the derivative type (real, imaginary or complex). + +**Returns** + +The derivative type. + + + +### options + +Return the union of estimator options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + estimator options. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values, parameters=None, **options)` + +Run the job of the estimator gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – The list of observables. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th element of the i-th result corresponds to the gradient of the i-th circuit with respect to the j-th parameter. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombQGT.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombQGT.md new file mode 100644 index 00000000000..1e928f2d2ff --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombQGT.md @@ -0,0 +1,124 @@ +--- +title: LinCombQGT +description: API reference for qiskit.algorithms.gradients.LinCombQGT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.LinCombQGT +--- + +# LinCombQGT + + + +`qiskit.algorithms.gradients.LinCombQGT(estimator, phase_fix=True, derivative_type=DerivativeType.COMPLEX, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/lin_comb/lin_comb_qgt.py "view source code") + +Bases: [`BaseQGT`](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.base.base_qgt.BaseQGT") + +Computes the Quantum Geometric Tensor (QGT) given a pure, parameterized quantum state. + +This method employs a linear combination of unitaries \[1]. + +**Reference:** + +> **\[1]: Schuld et al., “Evaluating analytic gradients on quantum hardware” (2018).** +> +> [arXiv:1811.11184](https://arxiv.org/pdf/1811.11184.pdf) + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the QGT. + +* **phase\_fix** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to calculate the second term (phase fix) of the QGT, which is $\langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle$. Default to `True`. + +* **derivative\_type** (*DerivativeType*) – + + The type of derivative. Can be either `DerivativeType.REAL` `DerivativeType.IMAG`, or `DerivativeType.COMPLEX`. Defaults to `DerivativeType.REAL`. + + * `DerivativeType.REAL` computes + + $$ + \mathrm{Re(QGT)}_{ij}= \mathrm{Re}[\langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. + $$ + + * `DerivativeType.IMAG` computes + + $$ + \mathrm{Re(QGT)}_{ij}= \mathrm{Im}[\langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. + $$ + + * `DerivativeType.COMPLEX` computes + + $$ + \mathrm{QGT}_{ij}= [\langle \partial_i \psi | \partial_j \psi \rangle + - \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. + $$ + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Backend runtime options used for circuit execution. The order of priority is: options in `run` method > QGT’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['rx', 'ry', 'rz', 'rzx', 'rzz', 'ryy', 'rxx', 'cx', 'cy', 'cz', 'ccx', 'swap', 'iswap', 'h', 't', 's', 'sdg', 'x', 'y', 'z']` + + + +### derivative\_type + +The derivative type. + + + +### options + +Return the union of estimator options setting and QGT default options, where, if the same field is set in both, the QGT’s default options override the primitive’s default setting. + +**Returns** + +The QGT default + estimator options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the QGTs on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the QGTs. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the QGTs of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the QGTs of all parameters in each circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > QGT’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +**Returns** + +The job object of the QGTs of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombSamplerGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombSamplerGradient.md new file mode 100644 index 00000000000..88d20cf0b3a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.LinCombSamplerGradient.md @@ -0,0 +1,84 @@ +--- +title: LinCombSamplerGradient +description: API reference for qiskit.algorithms.gradients.LinCombSamplerGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.LinCombSamplerGradient +--- + +# LinCombSamplerGradient + + + +`qiskit.algorithms.gradients.LinCombSamplerGradient(sampler, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/lin_comb/lin_comb_sampler_gradient.py "view source code") + +Bases: [`BaseSamplerGradient`](qiskit.algorithms.gradients.BaseSamplerGradient "qiskit.algorithms.gradients.base.base_sampler_gradient.BaseSamplerGradient") + +Compute the gradients of the sampling probability. This method employs a linear combination of unitaries \[1]. + +**Reference:** \[1] Schuld et al., Evaluating analytic gradients on quantum hardware, 2018 [arXiv:1811.11184](https://arxiv.org/pdf/1811.11184.pdf) + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler used to compute the gradients. +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['rx', 'ry', 'rz', 'rzx', 'rzz', 'ryy', 'rxx', 'cx', 'cy', 'cz', 'ccx', 'swap', 'iswap', 'h', 't', 's', 'sdg', 'x', 'y', 'z']` + + + +### options + +Return the union of sampler options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + sampler options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the sampler gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the sampling probability. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th quasi-probability distribution in the i-th result corresponds to the gradients of the sampling probability for the j-th parameter in `circuits[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftEstimatorGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftEstimatorGradient.md new file mode 100644 index 00000000000..8322b6fc9e6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftEstimatorGradient.md @@ -0,0 +1,106 @@ +--- +title: ParamShiftEstimatorGradient +description: API reference for qiskit.algorithms.gradients.ParamShiftEstimatorGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.ParamShiftEstimatorGradient +--- + +# ParamShiftEstimatorGradient + + + +`qiskit.algorithms.gradients.ParamShiftEstimatorGradient(estimator, options=None, derivative_type=DerivativeType.REAL)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/param_shift/param_shift_estimator_gradient.py "view source code") + +Bases: [`BaseEstimatorGradient`](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.base.base_estimator_gradient.BaseEstimatorGradient") + +Compute the gradients of the expectation values by the parameter shift rule \[1]. + +**Reference:** \[1] Schuld, M., Bergholm, V., Gogolin, C., Izaac, J., and Killoran, N. Evaluating analytic gradients on quantum hardware, [DOI](https://doi.org/10.1103/PhysRevA.99.032331) + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the gradients. + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +* **derivative\_type** (*DerivativeType*) – + + The type of derivative. Can be either `DerivativeType.REAL` `DerivativeType.IMAG`, or `DerivativeType.COMPLEX`. + + > * `DerivativeType.REAL` computes $2 \mathrm{Re}[⟨ψ(ω)|O(θ)|dω ψ(ω)〉]$. + > * `DerivativeType.IMAG` computes $2 \mathrm{Im}[⟨ψ(ω)|O(θ)|dω ψ(ω)〉]$. + > * `DerivativeType.COMPLEX` computes $2 ⟨ψ(ω)|O(θ)|dω ψ(ω)〉$. + + Defaults to `DerivativeType.REAL`, as this yields e.g. the commonly-used energy gradient and this type is the only supported type for function-level schemes like finite difference. + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['x', 'y', 'z', 'h', 'rx', 'ry', 'rz', 'p', 'cx', 'cy', 'cz', 'ryy', 'rxx', 'rzz', 'rzx']` + + + +### derivative\_type + +Return the derivative type (real, imaginary or complex). + +**Returns** + +The derivative type. + + + +### options + +Return the union of estimator options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + estimator options. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values, parameters=None, **options)` + +Run the job of the estimator gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – The list of observables. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th element of the i-th result corresponds to the gradient of the i-th circuit with respect to the j-th parameter. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftSamplerGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftSamplerGradient.md new file mode 100644 index 00000000000..b16ba99356d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ParamShiftSamplerGradient.md @@ -0,0 +1,84 @@ +--- +title: ParamShiftSamplerGradient +description: API reference for qiskit.algorithms.gradients.ParamShiftSamplerGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.ParamShiftSamplerGradient +--- + +# ParamShiftSamplerGradient + + + +`qiskit.algorithms.gradients.ParamShiftSamplerGradient(sampler, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/param_shift/param_shift_sampler_gradient.py "view source code") + +Bases: [`BaseSamplerGradient`](qiskit.algorithms.gradients.BaseSamplerGradient "qiskit.algorithms.gradients.base.base_sampler_gradient.BaseSamplerGradient") + +Compute the gradients of the sampling probability by the parameter shift rule \[1]. + +**Reference:** \[1] Schuld, M., Bergholm, V., Gogolin, C., Izaac, J., and Killoran, N. Evaluating analytic gradients on quantum hardware, [DOI](https://doi.org/10.1103/PhysRevA.99.032331) + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler used to compute the gradients. +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['x', 'y', 'z', 'h', 'rx', 'ry', 'rz', 'p', 'cx', 'cy', 'cz', 'ryy', 'rxx', 'rzz', 'rzx']` + + + +### options + +Return the union of sampler options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + sampler options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the sampler gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the sampling probability. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th quasi-probability distribution in the i-th result corresponds to the gradients of the sampling probability for the j-th parameter in `circuits[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFI.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFI.md new file mode 100644 index 00000000000..f2526b1b2ef --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFI.md @@ -0,0 +1,77 @@ +--- +title: QFI +description: API reference for qiskit.algorithms.gradients.QFI +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.QFI +--- + +# QFI + + + +`qiskit.algorithms.gradients.QFI(qgt, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/qfi.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Computes the Quantum Fisher Information (QFI) given a pure, parameterized quantum state. QFI is defined as: + +$$ +\mathrm{QFI}_{ij}= 4 \mathrm{Re}[\langle \partial_i \psi | \partial_j \psi \rangle +- \langle\partial_i \psi | \psi \rangle \langle\psi | \partial_j \psi \rangle]. +$$ + +**Parameters** + +* **qgt** ([*BaseQGT*](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT")) – The quantum geometric tensor used to compute the QFI. +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Backend runtime options used for circuit execution. The order of priority is: options in `run` method > QFI’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +## Attributes + + + +### options + +Return the union of QGT’s options setting and QFI’s default options, where, if the same field is set in both, the QFI’s default options override the QGT’s default setting. + +**Returns** + +The QFI default + QGT options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the QFIs on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the QFIs. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the QFIs of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the QFIs of all parameters in each circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > QFI’s default options > QGT’s default setting. Higher priority setting overrides lower priority setting. + +**Returns** + +The job object of the QFIs of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFIResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFIResult.md new file mode 100644 index 00000000000..2508cc38001 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QFIResult.md @@ -0,0 +1,44 @@ +--- +title: QFIResult +description: API reference for qiskit.algorithms.gradients.QFIResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.QFIResult +--- + +# QFIResult + + + +`qiskit.algorithms.gradients.QFIResult(qfis, metadata, options)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/qfi_result.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Result of QFI. + +## Attributes + + + +### qfis + +`list[numpy.ndarray]` + +The QFI. + + + +### metadata + +`list[dict[str, Any]]` + +Additional information about the job. + + + +### options + +`Options` + +Primitive runtime options for the execution of the job. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QGTResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QGTResult.md new file mode 100644 index 00000000000..edae6cb653a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.QGTResult.md @@ -0,0 +1,52 @@ +--- +title: QGTResult +description: API reference for qiskit.algorithms.gradients.QGTResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.QGTResult +--- + +# QGTResult + + + +`qiskit.algorithms.gradients.QGTResult(qgts, derivative_type, metadata, options)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/base/qgt_result.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Result of QGT. + +## Attributes + + + +### qgts + +`list[numpy.ndarray]` + +The QGT. + + + +### derivative\_type + +`DerivativeType` + +The type of derivative. + + + +### metadata + +`list[dict[str, Any]]` + +Additional information about the job. + + + +### options + +`Options` + +Primitive runtime options for the execution of the job. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseEstimatorGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseEstimatorGradient.md new file mode 100644 index 00000000000..de777e4f0c5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseEstimatorGradient.md @@ -0,0 +1,104 @@ +--- +title: ReverseEstimatorGradient +description: API reference for qiskit.algorithms.gradients.ReverseEstimatorGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.ReverseEstimatorGradient +--- + +# ReverseEstimatorGradient + + + +`qiskit.algorithms.gradients.ReverseEstimatorGradient(derivative_type=DerivativeType.REAL)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/reverse/reverse_gradient.py "view source code") + +Bases: [`BaseEstimatorGradient`](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.base.base_estimator_gradient.BaseEstimatorGradient") + +Estimator gradients with the classically efficient reverse mode. + + + This gradient implementation is based on statevector manipulations and scales exponentially with the number of qubits. However, for small system sizes it can be very fast compared to circuit-based gradients. + + +This class implements the calculation of the expectation gradient as described in \[1]. By keeping track of two statevectors and iteratively sweeping through each parameterized gate, this method scales only linearly with the number of parameters. + +**References:** + +> **\[1]: Jones, T. and Gacon, J. “Efficient calculation of gradients in classical simulations** +> +> of variational quantum algorithms” (2020). [arXiv:2009.02823](https://arxiv.org/abs/2009.02823). + +**Parameters** + +**derivative\_type** (*DerivativeType*) – Defines whether the real, imaginary or real plus imaginary part of the gradient is returned. + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['rx', 'ry', 'rz', 'cp', 'crx', 'cry', 'crz']` + + + +### derivative\_type + +Return the derivative type (real, imaginary or complex). + +**Returns** + +The derivative type. + + + +### options + +Return the union of estimator options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + estimator options. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values, parameters=None, **options)` + +Run the job of the estimator gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – The list of observables. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th element of the i-th result corresponds to the gradient of the i-th circuit with respect to the j-th parameter. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseQGT.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseQGT.md new file mode 100644 index 00000000000..9ed09abdbcb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.ReverseQGT.md @@ -0,0 +1,100 @@ +--- +title: ReverseQGT +description: API reference for qiskit.algorithms.gradients.ReverseQGT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.ReverseQGT +--- + +# ReverseQGT + + + +`qiskit.algorithms.gradients.ReverseQGT(phase_fix=True, derivative_type=DerivativeType.COMPLEX)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/reverse/reverse_qgt.py "view source code") + +Bases: [`BaseQGT`](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.base.base_qgt.BaseQGT") + +QGT calculation with the classically efficient reverse mode. + + + This QGT implementation is based on statevector manipulations and scales exponentially with the number of qubits. However, for small system sizes it can be very fast compared to circuit-based gradients. + + +This class implements the calculation of the QGT as described in \[1]. By keeping track of three statevectors and iteratively sweeping through each parameterized gate, this method scales only quadratically with the number of parameters. + +**References:** + +> **\[1]: Jones, T. “Efficient classical calculation of the Quantum Natural Gradient” (2020).** +> +> [arXiv:2011.02991](https://arxiv.org/abs/2011.02991). + +**Parameters** + +* **phase\_fix** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether or not to include the phase fix. +* **derivative\_type** (*DerivativeType*) – Determines whether the complex QGT or only the real or imaginary parts are calculated. + +## Attributes + + + +### SUPPORTED\_GATES + +`= ['rx', 'ry', 'rz', 'cp', 'crx', 'cry', 'crz']` + + + +### derivative\_type + +The derivative type. + + + +### options + +There are no options for the reverse QGT, returns an empty options dict. + +**Returns** + +Empty options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the QGTs on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the QGTs. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the QGTs of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the QGTs of all parameters in each circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > QGT’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +**Returns** + +The job object of the QGTs of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSAEstimatorGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSAEstimatorGradient.md new file mode 100644 index 00000000000..267dce75047 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSAEstimatorGradient.md @@ -0,0 +1,96 @@ +--- +title: SPSAEstimatorGradient +description: API reference for qiskit.algorithms.gradients.SPSAEstimatorGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.SPSAEstimatorGradient +--- + +# SPSAEstimatorGradient + + + +`qiskit.algorithms.gradients.SPSAEstimatorGradient(estimator, epsilon, batch_size=1, seed=None, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/spsa/spsa_estimator_gradient.py "view source code") + +Bases: [`BaseEstimatorGradient`](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.base.base_estimator_gradient.BaseEstimatorGradient") + +Compute the gradients of the expectation value by the Simultaneous Perturbation Stochastic Approximation (SPSA) \[1]. + +**Reference:** \[1] J. C. Spall, Adaptive stochastic approximation by the simultaneous perturbation method in IEEE Transactions on Automatic Control, vol. 45, no. 10, pp. 1839-1853, Oct 2020, [doi: 10.1109/TAC.2000.880982](https://ieeexplore.ieee.org/document/880982) + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator used to compute the gradients. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The offset size for the SPSA gradients. +* **batch\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of gradients to average. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The seed for a random perturbation vector. +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `epsilon` is not positive. + +## Attributes + + + +### derivative\_type + +Return the derivative type (real, imaginary or complex). + +**Returns** + +The derivative type. + + + +### options + +Return the union of estimator options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + estimator options. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values, parameters=None, **options)` + +Run the job of the estimator gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*]*) – The list of observables. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the expectation values. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th element of the i-th result corresponds to the gradient of the i-th circuit with respect to the j-th parameter. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSASamplerGradient.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSASamplerGradient.md new file mode 100644 index 00000000000..4925431e787 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SPSASamplerGradient.md @@ -0,0 +1,85 @@ +--- +title: SPSASamplerGradient +description: API reference for qiskit.algorithms.gradients.SPSASamplerGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.SPSASamplerGradient +--- + +# SPSASamplerGradient + + + +`qiskit.algorithms.gradients.SPSASamplerGradient(sampler, epsilon, batch_size=1, seed=None, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/spsa/spsa_sampler_gradient.py "view source code") + +Bases: [`BaseSamplerGradient`](qiskit.algorithms.gradients.BaseSamplerGradient "qiskit.algorithms.gradients.base.base_sampler_gradient.BaseSamplerGradient") + +Compute the gradients of the sampling probability by the Simultaneous Perturbation Stochastic Approximation (SPSA) \[1]. + +**Reference:** \[1] J. C. Spall, Adaptive stochastic approximation by the simultaneous perturbation method in IEEE Transactions on Automatic Control, vol. 45, no. 10, pp. 1839-1853, Oct 2020, [doi: 10.1109/TAC.2000.880982](https://ieeexplore.ieee.org/document/880982). + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler used to compute the gradients. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The offset size for the SPSA gradients. +* **batch\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of gradients to average. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The seed for a random perturbation vector. +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `epsilon` is not positive. + +## Attributes + + + +### options + +Return the union of sampler options setting and gradient default options, where, if the same field is set in both, the gradient’s default options override the primitive’s default setting. + +**Returns** + +The gradient default + sampler options. + +## Methods + +### run + + + +`run(circuits, parameter_values, parameters=None, **options)` + +Run the job of the sampler gradient on the given circuits. + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The list of quantum circuits to compute the gradients. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – The list of parameter values to be bound to the circuit. +* **parameters** (*Sequence\[Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None] | None*) – The sequence of parameters to calculate only the gradients of the specified parameters. Each sequence of parameters corresponds to a circuit in `circuits`. Defaults to None, which means that the gradients of all parameters in each circuit are calculated. None in the sequence means that the gradients of all parameters in the corresponding circuit are calculated. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > gradient’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting + +**Returns** + +The job object of the gradients of the sampling probability. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. The j-th quasi-probability distribution in the i-th result corresponds to the gradients of the sampling probability for the j-th parameter in `circuits[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the gradient’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SamplerGradientResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SamplerGradientResult.md new file mode 100644 index 00000000000..a1fceb270a5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.SamplerGradientResult.md @@ -0,0 +1,44 @@ +--- +title: SamplerGradientResult +description: API reference for qiskit.algorithms.gradients.SamplerGradientResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.gradients.SamplerGradientResult +--- + +# SamplerGradientResult + + + +`qiskit.algorithms.gradients.SamplerGradientResult(gradients, metadata, options)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/gradients/base/sampler_gradient_result.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Result of SamplerGradient. + +## Attributes + + + +### gradients + +`list[list[dict[int, float]]]` + +The gradients of the sample probabilities. + + + +### metadata + +`list[dict[str, Any]]` + +Additional information about the job. + + + +### options + +`Options` + +Primitive runtime options for the execution of the job. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.gradients.md b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.md new file mode 100644 index 00000000000..d81968d4121 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.gradients.md @@ -0,0 +1,76 @@ +--- +title: gradients +description: API reference for qiskit.algorithms.gradients +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.gradients +--- + + + + + +# qiskit.algorithms.gradients + + + +## Gradients + + + +`qiskit.algorithms.gradients` + +### Base Classes + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [`BaseEstimatorGradient`](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient")(estimator\[, options, ...]) | Base class for an `EstimatorGradient` to compute the gradients of the expectation value. | +| [`BaseQGT`](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT")(estimator\[, phase\_fix, ...]) | Base class to computes the Quantum Geometric Tensor (QGT) given a pure, parameterized quantum state. | +| [`BaseSamplerGradient`](qiskit.algorithms.gradients.BaseSamplerGradient "qiskit.algorithms.gradients.BaseSamplerGradient")(sampler\[, options]) | Base class for a `SamplerGradient` to compute the gradients of the sampling probability. | +| [`EstimatorGradientResult`](qiskit.algorithms.gradients.EstimatorGradientResult "qiskit.algorithms.gradients.EstimatorGradientResult")(gradients, metadata, ...) | Result of EstimatorGradient. | +| [`SamplerGradientResult`](qiskit.algorithms.gradients.SamplerGradientResult "qiskit.algorithms.gradients.SamplerGradientResult")(gradients, metadata, ...) | Result of SamplerGradient. | +| [`QGTResult`](qiskit.algorithms.gradients.QGTResult "qiskit.algorithms.gradients.QGTResult")(qgts, derivative\_type, metadata, ...) | Result of QGT. | + +### Finite Differences + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| [`FiniteDiffEstimatorGradient`](qiskit.algorithms.gradients.FiniteDiffEstimatorGradient "qiskit.algorithms.gradients.FiniteDiffEstimatorGradient")(estimator, epsilon) | Compute the gradients of the expectation values by finite difference method \[1]. | +| [`FiniteDiffSamplerGradient`](qiskit.algorithms.gradients.FiniteDiffSamplerGradient "qiskit.algorithms.gradients.FiniteDiffSamplerGradient")(sampler, epsilon) | Compute the gradients of the sampling probability by finite difference method \[1]. | + +### Linear Combination of Unitaries + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | +| [`LinCombEstimatorGradient`](qiskit.algorithms.gradients.LinCombEstimatorGradient "qiskit.algorithms.gradients.LinCombEstimatorGradient")(estimator\[, ...]) | Compute the gradients of the expectation values. | +| [`LinCombSamplerGradient`](qiskit.algorithms.gradients.LinCombSamplerGradient "qiskit.algorithms.gradients.LinCombSamplerGradient")(sampler\[, options]) | Compute the gradients of the sampling probability. | +| [`LinCombQGT`](qiskit.algorithms.gradients.LinCombQGT "qiskit.algorithms.gradients.LinCombQGT")(estimator\[, phase\_fix, ...]) | Computes the Quantum Geometric Tensor (QGT) given a pure, parameterized quantum state. | + +### Parameter Shift Rules + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| [`ParamShiftEstimatorGradient`](qiskit.algorithms.gradients.ParamShiftEstimatorGradient "qiskit.algorithms.gradients.ParamShiftEstimatorGradient")(estimator\[, ...]) | Compute the gradients of the expectation values by the parameter shift rule \[1]. | +| [`ParamShiftSamplerGradient`](qiskit.algorithms.gradients.ParamShiftSamplerGradient "qiskit.algorithms.gradients.ParamShiftSamplerGradient")(sampler\[, options]) | Compute the gradients of the sampling probability by the parameter shift rule \[1]. | + +### Quantum Fisher Information + +| | | +| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| [`QFIResult`](qiskit.algorithms.gradients.QFIResult "qiskit.algorithms.gradients.QFIResult")(qfis, metadata, options) | Result of QFI. | +| [`QFI`](qiskit.algorithms.gradients.QFI "qiskit.algorithms.gradients.QFI")(qgt\[, options]) | Computes the Quantum Fisher Information (QFI) given a pure, parameterized quantum state. | + +### Classical Methods + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| [`ReverseEstimatorGradient`](qiskit.algorithms.gradients.ReverseEstimatorGradient "qiskit.algorithms.gradients.ReverseEstimatorGradient")(\[derivative\_type]) | Estimator gradients with the classically efficient reverse mode. | +| [`ReverseQGT`](qiskit.algorithms.gradients.ReverseQGT "qiskit.algorithms.gradients.ReverseQGT")(\[phase\_fix, derivative\_type]) | QGT calculation with the classically efficient reverse mode. | + +### Simultaneous Perturbation Stochastic Approximation + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| [`SPSAEstimatorGradient`](qiskit.algorithms.gradients.SPSAEstimatorGradient "qiskit.algorithms.gradients.SPSAEstimatorGradient")(estimator, epsilon\[, ...]) | Compute the gradients of the expectation value by the Simultaneous Perturbation Stochastic Approximation (SPSA) \[1]. | +| [`SPSASamplerGradient`](qiskit.algorithms.gradients.SPSASamplerGradient "qiskit.algorithms.gradients.SPSASamplerGradient")(sampler, epsilon\[, ...]) | Compute the gradients of the sampling probability by the Simultaneous Perturbation Stochastic Approximation (SPSA) \[1]. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQE.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQE.md new file mode 100644 index 00000000000..2b818c6e3f7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQE.md @@ -0,0 +1,143 @@ +--- +title: AdaptVQE +description: API reference for qiskit.algorithms.minimum_eigensolvers.AdaptVQE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.AdaptVQE +--- + +# AdaptVQE + + + +`qiskit.algorithms.minimum_eigensolvers.AdaptVQE(solver, *, gradient_threshold=1e-05, eigenvalue_threshold=1e-05, max_iterations=None, threshold=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/adapt_vqe.py "view source code") + +Bases: `VariationalAlgorithm`, [`MinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.minimum_eigensolver.MinimumEigensolver") + +The Adaptive Variational Quantum Eigensolver algorithm. + +[AdaptVQE](https://arxiv.org/abs/1812.11173) is a quantum algorithm which creates a compact ansatz from a set of evolution operators. It iteratively extends the ansatz circuit, by selecting the building block that leads to the largest gradient from a set of candidates. In chemistry, this is usually a list of orbital excitations. Thus, a common choice of ansatz to be used with this algorithm is the Unitary Coupled Cluster ansatz implemented in Qiskit Nature. This results in a wavefunction ansatz which is uniquely adapted to the operator whose minimum eigenvalue is being determined. This class relies on a supplied instance of [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE") to find the minimum eigenvalue. The performance of AdaptVQE significantly depends on the minimization routine. + +```python +from qiskit.algorithms.minimum_eigensolvers import AdaptVQE, VQE +from qiskit.algorithms.optimizers import SLSQP +from qiskit.primitives import Estimator +from qiskit.circuit.library import EvolvedOperatorAnsatz + +# get your Hamiltonian +hamiltonian = ... + +# construct your ansatz +ansatz = EvolvedOperatorAnsatz(...) + +vqe = VQE(Estimator(), ansatz, SLSQP()) + +adapt_vqe = AdaptVQE(vqe) + +eigenvalue, _ = adapt_vqe.compute_minimum_eigenvalue(hamiltonian) +``` + +The following attributes can be set via the initializer but can also be read and updated once the AdaptVQE object has been constructed. + + + +### solver + +a [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE") instance used internally to compute the minimum eigenvalues. It is a requirement that the [`ansatz`](qiskit.algorithms.minimum_eigensolvers.VQE#ansatz "qiskit.algorithms.minimum_eigensolvers.VQE.ansatz") of this solver is of type [`EvolvedOperatorAnsatz`](qiskit.circuit.library.EvolvedOperatorAnsatz "qiskit.circuit.library.EvolvedOperatorAnsatz"). + + + +### gradient\_threshold + +once all gradients have an absolute value smaller than this threshold, the algorithm has converged and terminates. + + + +### eigenvalue\_threshold + +once the eigenvalue has changed by less than this threshold from one iteration to the next, the algorithm has converged and terminates. When this case occurs, the excitation included in the final iteration did not result in a significant improvement of the eigenvalue and, thus, the results from this iteration are not considered. + + + +### max\_iterations + +the maximum number of iterations for the adaptive loop. If `None`, the algorithm is not bound in its number of iterations. + + + `qiskit.algorithms.minimum_eigensolvers.adapt_vqe.AdaptVQE.__init__()`’s argument `threshold` is pending deprecation as of qiskit-terra 0.24.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use the argument `gradient_threshold`, which behaves identically. + + +**Parameters** + +* **solver** ([*VQE*](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE")) – a [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE") instance used internally to compute the minimum eigenvalues. It is a requirement that the [`ansatz`](qiskit.algorithms.minimum_eigensolvers.VQE#ansatz "qiskit.algorithms.minimum_eigensolvers.VQE.ansatz") of this solver is of type [`EvolvedOperatorAnsatz`](qiskit.circuit.library.EvolvedOperatorAnsatz "qiskit.circuit.library.EvolvedOperatorAnsatz"). +* **gradient\_threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – once all gradients have an absolute value smaller than this threshold, the algorithm has converged and terminates. +* **eigenvalue\_threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – once the eigenvalue has changed by less than this threshold from one iteration to the next, the algorithm has converged and terminates. When this case occurs, the excitation included in the final iteration did not result in a significant improvement of the eigenvalue and, thus, the results from this iteration are not considered. +* **max\_iterations** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – the maximum number of iterations for the adaptive loop. If `None`, the algorithm is not bound in its number of iterations. +* **threshold** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – once all gradients have an absolute value smaller than this threshold, the algorithm has converged and terminates. Defaults to `1e-5`. + +## Attributes + + + +### initial\_point + +Returns the initial point of the internal [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE") solver. + + + +### threshold + +The threshold for the gradients. + +Once all gradients have an absolute value smaller than this threshold, the algorithm has converged and terminates. + + + The property `qiskit.algorithms.minimum_eigensolvers.adapt_vqe.AdaptVQE.threshold` is pending deprecation as of qiskit-terra 0.24.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use the gradient\_threshold attribute. + + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes the minimum eigenvalue. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Operator whose minimum eigenvalue we want to find. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Additional auxiliary operators to evaluate. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If an ansatz other than [`EvolvedOperatorAnsatz`](qiskit.circuit.library.EvolvedOperatorAnsatz "qiskit.circuit.library.EvolvedOperatorAnsatz") is provided. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If all evaluated gradients lie below the convergence threshold in the first iteration of the algorithm. + +**Returns** + +An [`AdaptVQEResult`](qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult "qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult") which is a [`VQEResult`](qiskit.algorithms.minimum_eigensolvers.VQEResult "qiskit.algorithms.minimum_eigensolvers.VQEResult") but also but also includes runtime information about the AdaptVQE algorithm like the number of iterations, termination criterion, and the final maximum gradient. + +**Return type** + +[AdaptVQEResult](qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult "qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenvalue of the main `operator` then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult.md new file mode 100644 index 00000000000..df1b52a7773 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult.md @@ -0,0 +1,122 @@ +--- +title: AdaptVQEResult +description: API reference for qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult +--- + +# AdaptVQEResult + + + +`qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/adapt_vqe.py "view source code") + +Bases: [`VQEResult`](qiskit.algorithms.minimum_eigensolvers.VQEResult "qiskit.algorithms.minimum_eigensolvers.vqe.VQEResult") + +AdaptVQE Result. + +## Attributes + + + +### aux\_operators\_evaluated + +The aux operator expectation values. + +These values are in fact tuples formatted as (mean, (variance, shots)). + + + +### cost\_function\_evals + +The number of cost optimizer evaluations. + + + +### eigenvalue + +The computed minimum eigenvalue. + + + +### eigenvalue\_history + +Returns the history of computed eigenvalues. + +The history’s length matches the number of iterations and includes the final computed value. + + + +### final\_max\_gradient + +Returns the final maximum gradient. + + + +### num\_iterations + +Returns the number of iterations. + + + +### optimal\_circuit + +The optimal circuits. Along with the optimal parameters, these can be used to retrieve the minimum eigenstate. + + + +### optimal\_parameters + +Returns the optimal parameters in a dictionary + + + +### optimal\_point + +Returns optimal point + + + +### optimal\_value + +Returns optimal value + + + +### optimizer\_evals + +Returns number of optimizer evaluations + + + +### optimizer\_result + +Returns the optimizer result + + + +### optimizer\_time + +Returns time taken for optimization + + + +### termination\_criterion + +Returns the termination criterion. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver.md new file mode 100644 index 00000000000..24547fd50b7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver.md @@ -0,0 +1,61 @@ +--- +title: MinimumEigensolver +description: API reference for qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver +--- + +# MinimumEigensolver + + + +`qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/minimum_eigensolver.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +The minimum eigensolver interface. + +Algorithms that can compute a minimum eigenvalue for an operator may implement this interface to allow different algorithms to be used interchangeably. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`abstract compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes the minimum eigenvalue. The `operator` and `aux_operators` are supplied here. While an `operator` is required by algorithms, `aux_operators` are optional. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Qubit operator of the observable. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the parameters of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators and total particle count operators, so we can get values for these at the ground state. + +**Returns** + +A minimum eigensolver result. + +**Return type** + +[MinimumEigensolverResult](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenvalue of the main `operator` then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult.md new file mode 100644 index 00000000000..f266555b086 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult.md @@ -0,0 +1,48 @@ +--- +title: MinimumEigensolverResult +description: API reference for qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult +--- + +# MinimumEigensolverResult + + + +`qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/minimum_eigensolver.py "view source code") + +Bases: `AlgorithmResult` + +Minimum eigensolver result. + +## Attributes + + + +### aux\_operators\_evaluated + +The aux operator expectation values. + +These values are in fact tuples formatted as (mean, (variance, shots)). + + + +### eigenvalue + +The computed minimum eigenvalue. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver.md new file mode 100644 index 00000000000..241eb954e2b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver.md @@ -0,0 +1,71 @@ +--- +title: NumPyMinimumEigensolver +description: API reference for qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver +--- + +# NumPyMinimumEigensolver + + + +`qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver(filter_criterion=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/numpy_minimum_eigensolver.py "view source code") + +Bases: [`MinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.minimum_eigensolver.MinimumEigensolver") + +The NumPy minimum eigensolver algorithm. + +**Parameters** + +**filter\_criterion** (*FilterType | None*) – Callable that allows to filter eigenvalues/eigenstates. The minimum eigensolver is only searching over feasible states and returns an eigenstate that has the smallest eigenvalue among feasible states. The callable has the signature `filter(eigenstate, eigenvalue, aux_values)` and must return a boolean to indicate whether to consider this value or not. If there is no feasible element, the result can even be empty. + +## Attributes + + + +### filter\_criterion + +Returns the criterion for filtering eigenstates/eigenvalues. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes the minimum eigenvalue. The `operator` and `aux_operators` are supplied here. While an `operator` is required by algorithms, `aux_operators` are optional. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Qubit operator of the observable. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the parameters of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators and total particle count operators, so we can get values for these at the ground state. + +**Returns** + +A minimum eigensolver result. + +**Return type** + +[NumPyMinimumEigensolverResult](qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenvalue of the main `operator` then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult.md new file mode 100644 index 00000000000..f069d8c2da4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult.md @@ -0,0 +1,54 @@ +--- +title: NumPyMinimumEigensolverResult +description: API reference for qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult +--- + +# NumPyMinimumEigensolverResult + + + +`qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/numpy_minimum_eigensolver.py "view source code") + +Bases: [`MinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.minimum_eigensolver.MinimumEigensolverResult") + +NumPy minimum eigensolver result. + +## Attributes + + + +### aux\_operators\_evaluated + +The aux operator expectation values. + +These values are in fact tuples formatted as (mean, (variance, shots)). + + + +### eigenstate + +Returns the eigenstate corresponding to the computed minimum eigenvalue. + + + +### eigenvalue + +The computed minimum eigenvalue. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.QAOA.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.QAOA.md new file mode 100644 index 00000000000..eaa30f6196f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.QAOA.md @@ -0,0 +1,172 @@ +--- +title: QAOA +description: API reference for qiskit.algorithms.minimum_eigensolvers.QAOA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.QAOA +--- + +# QAOA + + + +`qiskit.algorithms.minimum_eigensolvers.QAOA(sampler, optimizer, *, reps=1, initial_state=None, mixer=None, initial_point=None, aggregation=None, callback=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/qaoa.py "view source code") + +Bases: [`SamplingVQE`](qiskit.algorithms.minimum_eigensolvers.SamplingVQE "qiskit.algorithms.minimum_eigensolvers.sampling_vqe.SamplingVQE") + +The Quantum Approximate Optimization Algorithm (QAOA). + +QAOA is a well-known algorithm for finding approximate solutions to combinatorial-optimization problems \[1]. + +The QAOA implementation directly extends [`SamplingVQE`](qiskit.algorithms.minimum_eigensolvers.SamplingVQE "qiskit.algorithms.minimum_eigensolvers.SamplingVQE") and inherits its optimization structure. However, unlike VQE, which can be configured with arbitrary ansatzes, QAOA uses its own fine-tuned ansatz, which comprises $p$ parameterized global $x$ rotations and $p$ different parameterizations of the problem hamiltonian. QAOA is thus principally configured by the single integer parameter, `reps`, which dictates the depth of the ansatz, and thus affects the approximation quality. + +An optional array of $2p$ parameter values, as the [`initial_point`](#qiskit.algorithms.minimum_eigensolvers.QAOA.initial_point "qiskit.algorithms.minimum_eigensolvers.QAOA.initial_point"), may be provided as the starting $\beta$ and $\gamma$ parameters for the QAOA ansatz \[1]. + +An operator or a parameterized quantum circuit may optionally also be provided as a custom [`mixer`](#qiskit.algorithms.minimum_eigensolvers.QAOA.mixer "qiskit.algorithms.minimum_eigensolvers.QAOA.mixer") Hamiltonian. This allows in the case of quantum annealing \[2] and QAOA \[3], to run constrained optimization problems where the mixer constrains the evolution to a feasible subspace of the full Hilbert space. + +The following attributes can be set via the initializer but can also be read and updated once the QAOA object has been constructed. + + + +### sampler + +The sampler primitive to sample the circuits. + +**Type** + +[BaseSampler](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") + + + +### optimizer + +A classical optimizer to find the minimum energy. This can either be a Qiskit [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable implementing the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. + +**Type** + +[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") | [Minimizer](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") + + + +### reps + +The integer parameter $p$. Has a minimum valid value of 1. + +**Type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### initial\_state + +An optional initial state to prepend the QAOA circuit with. + + + +### mixer + +The mixer Hamiltonian to evolve with or a custom quantum circuit. Allows support of optimizations in constrained subspaces \[2, 3] as well as warm-starting the optimization \[4]. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") | BaseOperator | [PauliSumOp](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") + + + +### aggregation + +A float or callable to specify how the objective function evaluated on the basis states should be aggregated. If a float, this specifies the $\alpha \in [0,1]$ parameter for a CVaR expectation value. + +**Type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | Callable\[\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] | None + + + +### callback + +A callback that can access the intermediate data at each optimization step. These data are: the evaluation count, the optimizer parameters for the ansatz, the evaluated value, the the metadata dictionary, and the best measurement. + +**Type** + +Callable\[\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), np.ndarray, [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), Any]], None] | None + +**References** + +**\[1]: Farhi, E., Goldstone, J., Gutmann, S., “A Quantum Approximate Optimization Algorithm”** + +[arXiv:1411.4028](https://arxiv.org/abs/1411.4028) + +**\[2]: Hen, I., Spedalieri, F. M., “Quantum Annealing for Constrained Optimization”** + +[PhysRevApplied.5.034007](https://doi.org/10.1103/PhysRevApplied.5.034007) + +**\[3]: Hadfield, S. et al, “From the Quantum Approximate Optimization Algorithm to a Quantum** + +Alternating Operator Ansatz” [arXiv:1709.03489](https://arxiv.org/abs/1709.03489) + +**\[4]: Egger, D. J., Marecek, J., Woerner, S., “Warm-starting quantum optimization”** + +[arXiv: 2009.10095](https://arxiv.org/abs/2009.10095) + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler primitive to sample the circuits. +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer")) – A classical optimizer to find the minimum energy. This can either be a Qiskit [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable implementing the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The integer parameter $p$. Has a minimum valid value of 1. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – An optional initial state to prepend the QAOA circuit with. +* **mixer** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| BaseOperator |*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – The mixer Hamiltonian to evolve with or a custom quantum circuit. Allows support of optimizations in constrained subspaces \[2, 3] as well as warm-starting the optimization \[4]. +* **initial\_point** (*np.ndarray | None*) – An optional initial point (i.e. initial parameter values) for the optimizer. The length of the initial point must match the number of `ansatz` parameters. If `None`, a random point will be generated within certain parameter bounds. `QAOA` will look to the ansatz for these bounds. If the ansatz does not specify bounds, bounds of $-2\pi$, $2\pi$ will be used. +* **aggregation** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| Callable\[\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A float or callable to specify how the objective function evaluated on the basis states should be aggregated. If a float, this specifies the $\alpha \in [0,1]$ parameter for a CVaR expectation value. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any]], None] | None*) – A callback that can access the intermediate data at each optimization step. These data are: the evaluation count, the optimizer parameters for the ansatz, the evaluated value, the metadata dictionary. + +## Attributes + + + +### initial\_point + +Return the initial point. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Compute the minimum eigenvalue of a diagonal operator. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Diagonal qubit operator. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the final state. + +**Returns** + +A [`SamplingMinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult") containing the optimization result. + +**Return type** + +[SamplingMinimumEigensolverResult](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver.md new file mode 100644 index 00000000000..9e5c8a06871 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver.md @@ -0,0 +1,59 @@ +--- +title: SamplingMinimumEigensolver +description: API reference for qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver +--- + +# SamplingMinimumEigensolver + + + +`qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/sampling_mes.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +The Sampling Minimum Eigensolver Interface. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`abstract compute_minimum_eigenvalue(operator, aux_operators=None)` + +Compute the minimum eigenvalue of a diagonal operator. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Diagonal qubit operator. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the final state. + +**Returns** + +A [`SamplingMinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult") containing the optimization result. + +**Return type** + +[SamplingMinimumEigensolverResult](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult.md new file mode 100644 index 00000000000..7151188f85a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult.md @@ -0,0 +1,66 @@ +--- +title: SamplingMinimumEigensolverResult +description: API reference for qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult +--- + +# SamplingMinimumEigensolverResult + + + +`qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/sampling_mes.py "view source code") + +Bases: `AlgorithmResult` + +Sampling Minimum Eigensolver Result. + +In contrast to the result of a `MinimumEigenSolver`, this result also contains the best measurement of the overall optimization and the samples of the final state. + +## Attributes + + + +### aux\_operators\_evaluated + +Return aux operator expectation values and metadata. + +These are formatted as (mean, metadata). + + + +### best\_measurement + +Return the best measurement over the entire optimization. + +Possesses keys: `state`, `bitstring`, `value`, `probability`. + + + +### eigenstate + +Return the quasi-distribution sampled from the final state. + +The ansatz is sampled when parameterized with the optimal parameters that where obtained computing the minimum eigenvalue. The keys represent a measured classical value and the value is a float for the quasi-probability of that result. + + + +### eigenvalue + +Return the approximation to the eigenvalue. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQE.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQE.md new file mode 100644 index 00000000000..111a7b339d0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQE.md @@ -0,0 +1,168 @@ +--- +title: SamplingVQE +description: API reference for qiskit.algorithms.minimum_eigensolvers.SamplingVQE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.SamplingVQE +--- + +# SamplingVQE + + + +`qiskit.algorithms.minimum_eigensolvers.SamplingVQE(sampler, ansatz, optimizer, *, initial_point=None, aggregation=None, callback=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/sampling_vqe.py "view source code") + +Bases: `VariationalAlgorithm`, [`SamplingMinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.sampling_mes.SamplingMinimumEigensolver") + +The Variational Quantum Eigensolver algorithm, optimized for diagonal Hamiltonians. + +VQE is a hybrid quantum-classical algorithm that uses a variational technique to find the minimum eigenvalue of a given diagonal Hamiltonian operator $H_{\text{diag}}$. + +In contrast to the [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE") class, the `SamplingVQE` algorithm is executed using a [`sampler`](#qiskit.algorithms.minimum_eigensolvers.SamplingVQE.sampler "qiskit.algorithms.minimum_eigensolvers.SamplingVQE.sampler") primitive. + +An instance of `SamplingVQE` also requires an [`ansatz`](#qiskit.algorithms.minimum_eigensolvers.SamplingVQE.ansatz "qiskit.algorithms.minimum_eigensolvers.SamplingVQE.ansatz"), a parameterized [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), to prepare the trial state $|\psi(\vec\theta)\rangle$. It also needs a classical [`optimizer`](#qiskit.algorithms.minimum_eigensolvers.SamplingVQE.optimizer "qiskit.algorithms.minimum_eigensolvers.SamplingVQE.optimizer") which varies the circuit parameters $\vec\theta$ to minimize the objective function, which depends on the chosen [`aggregation`](#qiskit.algorithms.minimum_eigensolvers.SamplingVQE.aggregation "qiskit.algorithms.minimum_eigensolvers.SamplingVQE.aggregation"). + +The optimizer can either be one of Qiskit’s optimizers, such as [`SPSA`](qiskit.algorithms.optimizers.SPSA "qiskit.algorithms.optimizers.SPSA") or a callable with the following signature: + +```python +from qiskit.algorithms.optimizers import OptimizerResult + +def my_minimizer(fun, x0, jac=None, bounds=None) -> OptimizerResult: + # Note that the callable *must* have these argument names! + # Args: + # fun (callable): the function to minimize + # x0 (np.ndarray): the initial point for the optimization + # jac (callable, optional): the gradient of the objective function + # bounds (list, optional): a list of tuples specifying the parameter bounds + + result = OptimizerResult() + result.x = # optimal parameters + result.fun = # optimal function value + return result +``` + +The above signature also allows one to use any SciPy minimizer, for instance as + +```python +from functools import partial +from scipy.optimize import minimize + +optimizer = partial(minimize, method="L-BFGS-B") +``` + +The following attributes can be set via the initializer but can also be read and updated once the `SamplingVQE` object has been constructed. + + + +### sampler + +The sampler primitive to sample the circuits. + +**Type** + +[BaseSampler](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") + + + +### ansatz + +A parameterized quantum circuit to prepare the trial state. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + + + +### optimizer + +A classical optimizer to find the minimum energy. This can either be a Qiskit [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable implementing the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. + +**Type** + +[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") | [Minimizer](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") + + + +### aggregation + +A float or callable to specify how the objective function evaluated on the basis states should be aggregated. If a float, this specifies the $\alpha \in [0,1]$ parameter for a CVaR expectation value \[1]. If a callable, it takes a list of basis state measurements specified as `[(probability, objective_value)]` and return an objective value as float. If None, all an ordinary expectation value is calculated. + +**Type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | Callable\[\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")]], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] | None + + + +### callback + +A callback that can access the intermediate data at each optimization step. These data are: the evaluation count, the optimizer parameters for the ansatz, the evaluated value, and the metadata dictionary. + +**Type** + +Callable\[\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), np.ndarray, [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), Any]], None] | None + +**References** + +**\[1]: Barkoutsos, P. K., Nannicini, G., Robert, A., Tavernelli, I., and Woerner, S.,** + +“Improving Variational Quantum Optimization using CVaR” [arXiv:1907.04769](https://arxiv.org/abs/1907.04769) + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – The sampler primitive to sample the circuits. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A parameterized quantum circuit to prepare the trial state. +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer")) – A classical optimizer to find the minimum energy. This can either be a Qiskit [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable implementing the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. +* **initial\_point** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – An optional initial point (i.e. initial parameter values) for the optimizer. The length of the initial point must match the number of [`ansatz`](#qiskit.algorithms.minimum_eigensolvers.SamplingVQE.ansatz "qiskit.algorithms.minimum_eigensolvers.SamplingVQE.ansatz") parameters. If `None`, a random point will be generated within certain parameter bounds. `SamplingVQE` will look to the ansatz for these bounds. If the ansatz does not specify bounds, bounds of $-2\pi$, $2\pi$ will be used. +* **aggregation** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| Callable\[\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A float or callable to specify how the objective function evaluated on the basis states should be aggregated. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any]], None] | None*) – A callback that can access the intermediate data at each optimization step. These data are: the evaluation count, the optimizer parameters for the ansatz, the estimated value, and the metadata dictionary. + +## Attributes + + + +### initial\_point + +Return the initial point. + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Compute the minimum eigenvalue of a diagonal operator. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Diagonal qubit operator. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the final state. + +**Returns** + +A [`SamplingMinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult") containing the optimization result. + +**Return type** + +[SamplingMinimumEigensolverResult](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenstate of the main operator then it can compute the expectation value of the aux\_operators for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult.md new file mode 100644 index 00000000000..7d26c4b94bd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult.md @@ -0,0 +1,112 @@ +--- +title: SamplingVQEResult +description: API reference for qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult +--- + +# SamplingVQEResult + + + +`qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/sampling_vqe.py "view source code") + +Bases: `VariationalResult`, [`SamplingMinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.sampling_mes.SamplingMinimumEigensolverResult") + +VQE Result. + +## Attributes + + + +### aux\_operators\_evaluated + +Return aux operator expectation values and metadata. + +These are formatted as (mean, metadata). + + + +### best\_measurement + +Return the best measurement over the entire optimization. + +Possesses keys: `state`, `bitstring`, `value`, `probability`. + + + +### cost\_function\_evals + +Returns number of cost optimizer evaluations + + + +### eigenstate + +Return the quasi-distribution sampled from the final state. + +The ansatz is sampled when parameterized with the optimal parameters that where obtained computing the minimum eigenvalue. The keys represent a measured classical value and the value is a float for the quasi-probability of that result. + + + +### eigenvalue + +Return the approximation to the eigenvalue. + + + +### optimal\_circuit + +The optimal circuits. Along with the optimal parameters, these can be used to retrieve the minimum eigenstate. + + + +### optimal\_parameters + +Returns the optimal parameters in a dictionary + + + +### optimal\_point + +Returns optimal point + + + +### optimal\_value + +Returns optimal value + + + +### optimizer\_evals + +Returns number of optimizer evaluations + + + +### optimizer\_result + +Returns the optimizer result + + + +### optimizer\_time + +Returns time taken for optimization + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQE.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQE.md new file mode 100644 index 00000000000..cf602d09778 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQE.md @@ -0,0 +1,172 @@ +--- +title: VQE +description: API reference for qiskit.algorithms.minimum_eigensolvers.VQE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.VQE +--- + +# VQE + + + +`qiskit.algorithms.minimum_eigensolvers.VQE(estimator, ansatz, optimizer, *, gradient=None, initial_point=None, callback=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/vqe.py "view source code") + +Bases: `VariationalAlgorithm`, [`MinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.minimum_eigensolver.MinimumEigensolver") + +The variational quantum eigensolver (VQE) algorithm. + +VQE is a hybrid quantum-classical algorithm that uses a variational technique to find the minimum eigenvalue of a given Hamiltonian operator $H$. + +The `VQE` algorithm is executed using an [`estimator`](#qiskit.algorithms.minimum_eigensolvers.VQE.estimator "qiskit.algorithms.minimum_eigensolvers.VQE.estimator") primitive, which computes expectation values of operators (observables). + +An instance of `VQE` also requires an [`ansatz`](#qiskit.algorithms.minimum_eigensolvers.VQE.ansatz "qiskit.algorithms.minimum_eigensolvers.VQE.ansatz"), a parameterized [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), to prepare the trial state $|\psi(\vec\theta)\rangle$. It also needs a classical [`optimizer`](#qiskit.algorithms.minimum_eigensolvers.VQE.optimizer "qiskit.algorithms.minimum_eigensolvers.VQE.optimizer") which varies the circuit parameters $\vec\theta$ such that the expectation value of the operator on the corresponding state approaches a minimum, + +$$ +\min_{\vec\theta} \langle\psi(\vec\theta)|H|\psi(\vec\theta)\rangle. +$$ + +The [`estimator`](#qiskit.algorithms.minimum_eigensolvers.VQE.estimator "qiskit.algorithms.minimum_eigensolvers.VQE.estimator") is used to compute this expectation value for every optimization step. + +The optimizer can either be one of Qiskit’s optimizers, such as [`SPSA`](qiskit.algorithms.optimizers.SPSA "qiskit.algorithms.optimizers.SPSA") or a callable with the following signature: + +```python +from qiskit.algorithms.optimizers import OptimizerResult + +def my_minimizer(fun, x0, jac=None, bounds=None) -> OptimizerResult: + # Note that the callable *must* have these argument names! + # Args: + # fun (callable): the function to minimize + # x0 (np.ndarray): the initial point for the optimization + # jac (callable, optional): the gradient of the objective function + # bounds (list, optional): a list of tuples specifying the parameter bounds + + result = OptimizerResult() + result.x = # optimal parameters + result.fun = # optimal function value + return result +``` + +The above signature also allows one to use any SciPy minimizer, for instance as + +```python +from functools import partial +from scipy.optimize import minimize + +optimizer = partial(minimize, method="L-BFGS-B") +``` + +The following attributes can be set via the initializer but can also be read and updated once the VQE object has been constructed. + + + +### estimator + +The estimator primitive to compute the expectation value of the Hamiltonian operator. + +**Type** + +[BaseEstimator](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") + + + +### ansatz + +A parameterized quantum circuit to prepare the trial state. + +**Type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + + + +### optimizer + +A classical optimizer to find the minimum energy. This can either be a Qiskit [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable implementing the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. + +**Type** + +[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") | [Minimizer](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") + + + +### gradient + +An optional estimator gradient to be used with the optimizer. + +**Type** + +[BaseEstimatorGradient](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient") | None + + + +### callback + +A callback that can access the intermediate data at each optimization step. These data are: the evaluation count, the optimizer parameters for the ansatz, the evaluated mean, and the metadata dictionary. + +**Type** + +Callable\[\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), np.ndarray, [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), Any]], None] | None + +**References** + +**\[1]: Peruzzo, A., et al, “A variational eigenvalue solver on a quantum processor”** + +[arXiv:1304.3061](https://arxiv.org/abs/1304.3061) + +**Parameters** + +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")) – The estimator primitive to compute the expectation value of the Hamiltonian operator. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A parameterized quantum circuit to prepare the trial state. +* **optimizer** ([*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *|*[*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer")) – A classical optimizer to find the minimum energy. This can either be a Qiskit [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") or a callable implementing the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol. +* **gradient** ([*BaseEstimatorGradient*](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient") *| None*) – An optional estimator gradient to be used with the optimizer. +* **initial\_point** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – An optional initial point (i.e. initial parameter values) for the optimizer. The length of the initial point must match the number of [`ansatz`](#qiskit.algorithms.minimum_eigensolvers.VQE.ansatz "qiskit.algorithms.minimum_eigensolvers.VQE.ansatz") parameters. If `None`, a random point will be generated within certain parameter bounds. `VQE` will look to the ansatz for these bounds. If the ansatz does not specify bounds, bounds of $-2\pi$, $2\pi$ will be used. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.ndarray,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any]], None] | None*) – A callback that can access the intermediate data at each optimization step. These data are: the evaluation count, the optimizer parameters for the ansatz, the estimated value, and the metadata dictionary. + +## Attributes + + + +### initial\_point + +## Methods + +### compute\_minimum\_eigenvalue + + + +`compute_minimum_eigenvalue(operator, aux_operators=None)` + +Computes the minimum eigenvalue. The `operator` and `aux_operators` are supplied here. While an `operator` is required by algorithms, `aux_operators` are optional. + +**Parameters** + +* **operator** (*BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")) – Qubit operator of the observable. +* **aux\_operators** (*ListOrDict\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")*] | None*) – Optional list of auxiliary operators to be evaluated with the parameters of the minimum eigenvalue main result and their expectation values returned. For instance in chemistry these can be dipole operators and total particle count operators, so we can get values for these at the ground state. + +**Returns** + +A minimum eigensolver result. + +**Return type** + +[VQEResult](qiskit.algorithms.minimum_eigensolvers.VQEResult "qiskit.algorithms.minimum_eigensolvers.VQEResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +If the minimum eigensolver computes an eigenvalue of the main `operator` then it can compute the expectation value of the `aux_operators` for that state. Otherwise they will be ignored. + +**Returns** + +True if aux\_operator expectations can be evaluated, False otherwise + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQEResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQEResult.md new file mode 100644 index 00000000000..8a66a5b25c7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.VQEResult.md @@ -0,0 +1,96 @@ +--- +title: VQEResult +description: API reference for qiskit.algorithms.minimum_eigensolvers.VQEResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.minimum_eigensolvers.VQEResult +--- + +# VQEResult + + + +`qiskit.algorithms.minimum_eigensolvers.VQEResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/minimum_eigensolvers/vqe.py "view source code") + +Bases: `VariationalResult`, [`MinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.minimum_eigensolver.MinimumEigensolverResult") + +Variational quantum eigensolver result. + +## Attributes + + + +### aux\_operators\_evaluated + +The aux operator expectation values. + +These values are in fact tuples formatted as (mean, (variance, shots)). + + + +### cost\_function\_evals + +The number of cost optimizer evaluations. + + + +### eigenvalue + +The computed minimum eigenvalue. + + + +### optimal\_circuit + +The optimal circuits. Along with the optimal parameters, these can be used to retrieve the minimum eigenstate. + + + +### optimal\_parameters + +Returns the optimal parameters in a dictionary + + + +### optimal\_point + +Returns optimal point + + + +### optimal\_value + +Returns optimal value + + + +### optimizer\_evals + +Returns number of optimizer evaluations + + + +### optimizer\_result + +Returns the optimizer result + + + +### optimizer\_time + +Returns time taken for optimization + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.md b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.md new file mode 100644 index 00000000000..a3bf30ea50c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.minimum_eigensolvers.md @@ -0,0 +1,43 @@ +--- +title: minimum_eigensolvers +description: API reference for qiskit.algorithms.minimum_eigensolvers +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.minimum_eigensolvers +--- + + + + + +# qiskit.algorithms.minimum\_eigensolvers + + + +## Minimum Eigensolvers Package + + + +`qiskit.algorithms.minimum_eigensolvers` + +### Minimum Eigensolvers + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| [`MinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver")() | The minimum eigensolver interface. | +| [`NumPyMinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver")(\[filter\_criterion]) | The NumPy minimum eigensolver algorithm. | +| [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE")(estimator, ansatz, optimizer, \*\[, ...]) | The variational quantum eigensolver (VQE) algorithm. | +| [`AdaptVQE`](qiskit.algorithms.minimum_eigensolvers.AdaptVQE "qiskit.algorithms.minimum_eigensolvers.AdaptVQE")(solver, \*\[, gradient\_threshold, ...]) | The Adaptive Variational Quantum Eigensolver algorithm. | +| [`SamplingMinimumEigensolver`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolver")() | The Sampling Minimum Eigensolver Interface. | +| [`SamplingVQE`](qiskit.algorithms.minimum_eigensolvers.SamplingVQE "qiskit.algorithms.minimum_eigensolvers.SamplingVQE")(sampler, ansatz, optimizer, \*\[, ...]) | The Variational Quantum Eigensolver algorithm, optimized for diagonal Hamiltonians. | +| [`QAOA`](qiskit.algorithms.minimum_eigensolvers.QAOA "qiskit.algorithms.minimum_eigensolvers.QAOA")(sampler, optimizer, \*\[, reps, ...]) | The Quantum Approximate Optimization Algorithm (QAOA). | + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| [`MinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult")() | Minimum eigensolver result. | +| [`NumPyMinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolverResult")() | NumPy minimum eigensolver result. | +| [`VQEResult`](qiskit.algorithms.minimum_eigensolvers.VQEResult "qiskit.algorithms.minimum_eigensolvers.VQEResult")() | Variational quantum eigensolver result. | +| [`AdaptVQEResult`](qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult "qiskit.algorithms.minimum_eigensolvers.AdaptVQEResult")() | AdaptVQE Result. | +| [`SamplingMinimumEigensolverResult`](qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult "qiskit.algorithms.minimum_eigensolvers.SamplingMinimumEigensolverResult")() | Sampling Minimum Eigensolver Result. | +| [`SamplingVQEResult`](qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult "qiskit.algorithms.minimum_eigensolvers.SamplingVQEResult")() | VQE Result. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ADAM.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ADAM.md new file mode 100644 index 00000000000..29caff17444 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ADAM.md @@ -0,0 +1,282 @@ +--- +title: ADAM +description: API reference for qiskit.algorithms.optimizers.ADAM +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.ADAM +--- + +# ADAM + + + +`qiskit.algorithms.optimizers.ADAM(maxiter=10000, tol=1e-06, lr=0.001, beta_1=0.9, beta_2=0.99, noise_factor=1e-08, eps=1e-10, amsgrad=False, snapshot_dir=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/adam_amsgrad.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Adam and AMSGRAD optimizers. + +Adam \[1] is a gradient-based optimization algorithm that is relies on adaptive estimates of lower-order moments. The algorithm requires little memory and is invariant to diagonal rescaling of the gradients. Furthermore, it is able to cope with non-stationary objective functions and noisy and/or sparse gradients. + +AMSGRAD \[2] (a variant of Adam) uses a ‘long-term memory’ of past gradients and, thereby, improves convergence properties. + +**References** + +**\[1]: Kingma, Diederik & Ba, Jimmy (2014), Adam: A Method for Stochastic Optimization.** + +[arXiv:1412.6980](https://arxiv.org/abs/1412.6980) + +**\[2]: Sashank J. Reddi and Satyen Kale and Sanjiv Kumar (2018),** + +On the Convergence of Adam and Beyond. [arXiv:1904.09237](https://arxiv.org/abs/1904.09237) + + + This component has some function that is normally random. If you want to reproduce behavior then you should set the random number generator seed in the algorithm\_globals (`qiskit.utils.algorithm_globals.random_seed = seed`). + + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of iterations +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Tolerance for termination +* **lr** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value >= 0, Learning rate. +* **beta\_1** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value in range 0 to 1, Generally close to 1. +* **beta\_2** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value in range 0 to 1, Generally close to 1. +* **noise\_factor** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value >= 0, Noise factor +* **eps** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value >=0, Epsilon to be used for finite differences if no analytic gradient method is given. +* **amsgrad** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True to use AMSGRAD, False if not +* **snapshot\_dir** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – If not None save the optimizer’s parameter after every step to the given directory + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### load\_params + + + +`load_params(load_dir)` + +Load iteration parameters for a file called `adam_params.csv`. + +**Parameters** + +**load\_dir** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The directory containing `adam_params.csv`. + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None, objective_function=None, initial_point=None, gradient_function=None)` + +Minimize the scalar function. + + + `qiskit.algorithms.optimizers.adam_amsgrad.ADAM.minimize()`’s argument `gradient_function` is deprecated as of qiskit-terra 0.19.0. It will be removed no earlier than 3 months after the release date. Instead, use the argument `jac`, which behaves identically. + + + + `qiskit.algorithms.optimizers.adam_amsgrad.ADAM.minimize()`’s argument `initial_point` is deprecated as of qiskit-terra 0.19.0. It will be removed no earlier than 3 months after the release date. Instead, use the argument `fun`, which behaves identically. + + + + `qiskit.algorithms.optimizers.adam_amsgrad.ADAM.minimize()`’s argument `objective_function` is deprecated as of qiskit-terra 0.19.0. It will be removed no earlier than 3 months after the release date. Instead, use the argument `fun`, which behaves identically. + + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. +* **objective\_function** (*Callable\[\[np.ndarray],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – DEPRECATED. A function handle to the objective function. +* **initial\_point** (*np.ndarray | None*) – DEPRECATED. The initial iteration point. +* **gradient\_function** (*Callable\[\[np.ndarray],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – DEPRECATED. A function handle to the gradient of the objective function. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### save\_params + + + +`save_params(snapshot_dir)` + +Save the current iteration parameters to a file called `adam_params.csv`. + + + The current parameters are appended to the file, if it exists already. The file is not overwritten. + + +**Parameters** + +**snapshot\_dir** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The directory to store the file in. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AQGD.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AQGD.md new file mode 100644 index 00000000000..65fa59ebbed --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AQGD.md @@ -0,0 +1,241 @@ +--- +title: AQGD +description: API reference for qiskit.algorithms.optimizers.AQGD +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.AQGD +--- + +# AQGD + + + +`qiskit.algorithms.optimizers.AQGD(maxiter=1000, eta=1.0, tol=1e-06, momentum=0.25, param_tol=1e-06, averaging=10)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/aqgd.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Analytic Quantum Gradient Descent (AQGD) with Epochs optimizer. Performs gradient descent optimization with a momentum term, analytic gradients, and customized step length schedule for parameterized quantum gates, i.e. Pauli Rotations. See, for example: + +* K. Mitarai, M. Negoro, M. Kitagawa, and K. Fujii. (2018). Quantum circuit learning. Phys. Rev. A 98, 032309. [https://arxiv.org/abs/1803.00745](https://arxiv.org/abs/1803.00745) +* Maria Schuld, Ville Bergholm, Christian Gogolin, Josh Izaac, Nathan Killoran. (2019). Evaluating analytic gradients on quantum hardware. Phys. Rev. A 99, 032331. [https://arxiv.org/abs/1811.11184](https://arxiv.org/abs/1811.11184) + +for further details on analytic gradients of parameterized quantum gates. + +Gradients are computed “analytically” using the quantum circuit when evaluating the objective function. + +Performs Analytical Quantum Gradient Descent (AQGD) with Epochs. + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Maximum number of iterations (full gradient steps) +* **eta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The coefficient of the gradient update. Increasing this value results in larger step sizes: param = previous\_param - eta \* deriv +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Tolerance for change in windowed average of objective values. Convergence occurs when either objective tolerance is met OR parameter tolerance is met. +* **momentum** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Bias towards the previous gradient momentum in current update. Must be within the bounds: \[0,1) +* **param\_tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Tolerance for change in norm of parameters. +* **averaging** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Length of window over which to average objective values for objective convergence criterion + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If the length of `maxiter`, momentum\`, and `eta` is not the same. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Support level dictionary + +**Returns** + +**gradient, bounds and initial point** + +support information that is ignored/required. + +**Return type** + +Dict\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AskData.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AskData.md new file mode 100644 index 00000000000..4de4e0e5852 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.AskData.md @@ -0,0 +1,43 @@ +--- +title: AskData +description: API reference for qiskit.algorithms.optimizers.AskData +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.AskData +--- + +# AskData + + + +`qiskit.algorithms.optimizers.AskData(x_fun=None, x_jac=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/steppable_optimizer.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for return type of [`ask()`](qiskit.algorithms.optimizers.SteppableOptimizer#ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask"). + +**Parameters** + +* **x\_fun** (*POINT |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[POINT] | None*) – Point or list of points where the function needs to be evaluated to compute the next +* **optimizer.** (*the next state of the*) – +* **x\_jac** (*POINT |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[POINT] | None*) – Point or list of points where the gradient/jacobian needs to be evaluated to compute +* **optimizer.** – + +## Attributes + + + +### x\_fun + +`POINT | list[POINT] | None` + +`= None` + + + +### x\_jac + +`POINT | list[POINT] | None` + +`= None` + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.BOBYQA.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.BOBYQA.md new file mode 100644 index 00000000000..b29803aece4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.BOBYQA.md @@ -0,0 +1,221 @@ +--- +title: BOBYQA +description: API reference for qiskit.algorithms.optimizers.BOBYQA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.BOBYQA +--- + +# BOBYQA + + + +`qiskit.algorithms.optimizers.BOBYQA(maxiter=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/bobyqa.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Bound Optimization BY Quadratic Approximation algorithm. + +BOBYQA finds local solutions to nonlinear, non-convex minimization problems with optional bound constraints, without requirement of derivatives of the objective function. + +Uses skquant.opt installed with pip install scikit-quant. For further detail, please refer to [https://github.com/scikit-quant/scikit-quant](https://github.com/scikit-quant/scikit-quant) and [https://qat4chem.lbl.gov/software](https://qat4chem.lbl.gov/software). + +**Parameters** + +**maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – scikit-quant not installed + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Returns support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CG.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CG.md new file mode 100644 index 00000000000..bf3d7b248dc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CG.md @@ -0,0 +1,224 @@ +--- +title: CG +description: API reference for qiskit.algorithms.optimizers.CG +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.CG +--- + +# CG + + + +`qiskit.algorithms.optimizers.CG(maxiter=20, disp=False, gtol=1e-05, tol=None, eps=1.4901161193847656e-08, options=None, max_evals_grouped=1, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/cg.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Conjugate Gradient optimizer. + +CG is an algorithm for the numerical solution of systems of linear equations whose matrices are symmetric and positive-definite. It is an *iterative algorithm* in that it uses an initial guess to generate a sequence of improving approximate solutions for a problem, in which each approximation is derived from the previous ones. It is often used to solve unconstrained optimization problems, such as energy minimization. + +Uses scipy.optimize.minimize CG. For further detail, please refer to [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of iterations to perform. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to print convergence messages. +* **gtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Gradient norm must be less than gtol before successful termination. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Tolerance for termination. +* **eps** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – If jac is approximated, use this value for the step size. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of default gradient evaluations performed simultaneously. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.COBYLA.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.COBYLA.md new file mode 100644 index 00000000000..5efae1d656e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.COBYLA.md @@ -0,0 +1,222 @@ +--- +title: COBYLA +description: API reference for qiskit.algorithms.optimizers.COBYLA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.COBYLA +--- + +# COBYLA + + + +`qiskit.algorithms.optimizers.COBYLA(maxiter=1000, disp=False, rhobeg=1.0, tol=None, options=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/cobyla.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Constrained Optimization By Linear Approximation optimizer. + +COBYLA is a numerical optimization method for constrained problems where the derivative of the objective function is not known. + +Uses scipy.optimize.minimize COBYLA. For further detail, please refer to [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to print convergence messages. +* **rhobeg** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Reasonable initial changes to the variables. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Final accuracy in the optimization (not precisely guaranteed). This is a lower bound on the size of the trust region. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CRS.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CRS.md new file mode 100644 index 00000000000..edefeb1c72a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.CRS.md @@ -0,0 +1,233 @@ +--- +title: CRS +description: API reference for qiskit.algorithms.optimizers.CRS +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.CRS +--- + +# CRS + + + +`qiskit.algorithms.optimizers.CRS(max_evals=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nlopts/crs.py "view source code") + +Bases: `NLoptOptimizer` + +Controlled Random Search (CRS) with local mutation optimizer. + +Controlled Random Search (CRS) with local mutation is part of the family of the CRS optimizers. The CRS optimizers start with a random population of points, and randomly evolve these points by heuristic rules. In the case of CRS with local mutation, the evolution is a randomized version of the [`NELDER_MEAD`](qiskit.algorithms.optimizers.NELDER_MEAD "qiskit.algorithms.optimizers.NELDER_MEAD") local optimizer. + +NLopt global optimizer, derivative-free. For further detail, please refer to [https://nlopt.readthedocs.io/en/latest/NLopt\_Algorithms/#controlled-random-search-crs-with-local-mutation](https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#controlled-random-search-crs-with-local-mutation) + +**Parameters** + +**max\_evals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – NLopt library not installed. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_nlopt\_optimizer + + + +`get_nlopt_optimizer()` + +Return NLopt optimizer type + +**Return type** + +*NLoptOptimizerType* + +### get\_support\_level + + + +`get_support_level()` + +return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L.md new file mode 100644 index 00000000000..9a6af11a6dc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L.md @@ -0,0 +1,235 @@ +--- +title: DIRECT_L +description: API reference for qiskit.algorithms.optimizers.DIRECT_L +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.DIRECT_L +--- + + + +# DIRECT\_L + + + +`qiskit.algorithms.optimizers.DIRECT_L(max_evals=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nlopts/direct_l.py "view source code") + +Bases: `NLoptOptimizer` + +DIviding RECTangles Locally-biased optimizer. + +DIviding RECTangles (DIRECT) is a deterministic-search algorithms based on systematic division of the search domain into increasingly smaller hyper-rectangles. The DIRECT-L version is a “locally biased” variant of DIRECT that makes the algorithm more biased towards local search, so that it is more efficient for functions with few local minima. + +NLopt global optimizer, derivative-free. For further detail, please refer to [http://nlopt.readthedocs.io/en/latest/NLopt\_Algorithms/#direct-and-direct-l](http://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#direct-and-direct-l) + +**Parameters** + +**max\_evals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – NLopt library not installed. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_nlopt\_optimizer + + + +`get_nlopt_optimizer()` + +Return NLopt optimizer type + +**Return type** + +*NLoptOptimizerType* + +### get\_support\_level + + + +`get_support_level()` + +return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L_RAND.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L_RAND.md new file mode 100644 index 00000000000..c45a5f38af2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.DIRECT_L_RAND.md @@ -0,0 +1,235 @@ +--- +title: DIRECT_L_RAND +description: API reference for qiskit.algorithms.optimizers.DIRECT_L_RAND +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.DIRECT_L_RAND +--- + + + +# DIRECT\_L\_RAND + + + +`qiskit.algorithms.optimizers.DIRECT_L_RAND(max_evals=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nlopts/direct_l_rand.py "view source code") + +Bases: `NLoptOptimizer` + +DIviding RECTangles Locally-biased Randomized optimizer. + +DIRECT-L RAND is the “locally biased” variant with some randomization in near-tie decisions. See also [`DIRECT_L`](qiskit.algorithms.optimizers.DIRECT_L "qiskit.algorithms.optimizers.DIRECT_L") + +NLopt global optimizer, derivative-free. For further detail, please refer to [http://nlopt.readthedocs.io/en/latest/NLopt\_Algorithms/#direct-and-direct-l](http://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#direct-and-direct-l) + +**Parameters** + +**max\_evals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – NLopt library not installed. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_nlopt\_optimizer + + + +`get_nlopt_optimizer()` + +Return NLopt optimizer type + +**Return type** + +*NLoptOptimizerType* + +### get\_support\_level + + + +`get_support_level()` + +return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ESCH.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ESCH.md new file mode 100644 index 00000000000..2de46484a51 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ESCH.md @@ -0,0 +1,235 @@ +--- +title: ESCH +description: API reference for qiskit.algorithms.optimizers.ESCH +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.ESCH +--- + +# ESCH + + + +`qiskit.algorithms.optimizers.ESCH(max_evals=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nlopts/esch.py "view source code") + +Bases: `NLoptOptimizer` + +ESCH evolutionary optimizer. + +ESCH is an evolutionary algorithm for global optimization that supports bound constraints only. Specifically, it does not support nonlinear constraints. + +NLopt global optimizer, derivative-free. For further detail, please refer to + +[http://nlopt.readthedocs.io/en/latest/NLopt\_Algorithms/#esch-evolutionary-algorithm](http://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#esch-evolutionary-algorithm) + +**Parameters** + +**max\_evals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – NLopt library not installed. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_nlopt\_optimizer + + + +`get_nlopt_optimizer()` + +Return NLopt optimizer type + +**Return type** + +*NLoptOptimizerType* + +### get\_support\_level + + + +`get_support_level()` + +return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GSLS.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GSLS.md new file mode 100644 index 00000000000..3b9f13d11e5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GSLS.md @@ -0,0 +1,342 @@ +--- +title: GSLS +description: API reference for qiskit.algorithms.optimizers.GSLS +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.GSLS +--- + +# GSLS + + + +`qiskit.algorithms.optimizers.GSLS(maxiter=10000, max_eval=10000, disp=False, sampling_radius=1e-06, sample_size_factor=1, initial_step_size=0.01, min_step_size=1e-10, step_size_multiplier=0.4, armijo_parameter=0.1, min_gradient_norm=1e-08, max_failed_rejection_sampling=50)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/gsls.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Gaussian-smoothed Line Search. + +An implementation of the line search algorithm described in [https://arxiv.org/pdf/1905.01332.pdf](https://arxiv.org/pdf/1905.01332.pdf), using gradient approximation based on Gaussian-smoothed samples on a sphere. + + + This component has some function that is normally random. If you want to reproduce behavior then you should set the random number generator seed in the algorithm\_globals (`qiskit.utils.algorithm_globals.random_seed = seed`). + + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of iterations. +* **max\_eval** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of evaluations. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to display convergence messages. +* **sampling\_radius** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Sampling radius to determine gradient estimate. +* **sample\_size\_factor** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The size of the sample set at each iteration is this number multiplied by the dimension of the problem, rounded to the nearest integer. +* **initial\_step\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Initial step size for the descent algorithm. +* **min\_step\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Minimum step size for the descent algorithm. +* **step\_size\_multiplier** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Step size reduction after unsuccessful steps, in the interval (0, 1). +* **armijo\_parameter** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Armijo parameter for sufficient decrease criterion, in the interval (0, 1). +* **min\_gradient\_norm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – If the gradient norm is below this threshold, the algorithm stops. +* **max\_failed\_rejection\_sampling** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of attempts to sample points within bounds. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary. + +**Returns** + +A dictionary containing the support levels for different options. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### gradient\_approximation + + + +`gradient_approximation(n, x, x_value, directions, sample_set_x, sample_set_y)` + +Construct gradient approximation from given sample. + +**Parameters** + +* **n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Dimension of the problem. +* **x** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Point around which the sample set was constructed. +* **x\_value** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Objective function value at x. +* **directions** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Directions of the sample points wrt the central point x, as a 2D array. +* **sample\_set\_x** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – x-coordinates of the sample set, one point per row, as a 2D array. +* **sample\_set\_y** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Objective function values of the points in sample\_set\_x, as a 1D array. + +**Returns** + +Gradient approximation at x, as a 1D array. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### ls\_optimize + + + +`ls_optimize(n, obj_fun, initial_point, var_lb, var_ub)` + +Run the line search optimization. + +**Parameters** + +* **n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Dimension of the problem. +* **obj\_fun** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)")*\[\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Objective function. +* **initial\_point** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Initial point. +* **var\_lb** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Vector of lower bounds on the decision variables. Vector elements can be -np.inf if the corresponding variable is unbounded from below. +* **var\_ub** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Vector of upper bounds on the decision variables. Vector elements can be np.inf if the corresponding variable is unbounded from below. + +**Returns** + +Final iterate as a vector, corresponding objective function value, number of evaluations, and norm of the gradient estimate. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the number of dimensions mismatches the size of the initial point or the length of the lower or upper bound. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### sample\_points + + + +`sample_points(n, x, num_points)` + +Sample `num_points` points around `x` on the `n`-sphere of specified radius. + +The radius of the sphere is `self._options['sampling_radius']`. + +**Parameters** + +* **n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Dimension of the problem. +* **x** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Point around which the sample set is constructed. +* **num\_points** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of points in the sample set. + +**Returns** + +A tuple containing the sampling points and the directions. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)"), [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")] + +### sample\_set + + + +`sample_set(n, x, var_lb, var_ub, num_points)` + +Construct sample set of given size. + +**Parameters** + +* **n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Dimension of the problem. +* **x** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Point around which the sample set is constructed. +* **var\_lb** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Vector of lower bounds on the decision variables. Vector elements can be -np.inf if the corresponding variable is unbounded from below. +* **var\_ub** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – Vector of lower bounds on the decision variables. Vector elements can be np.inf if the corresponding variable is unbounded from above. +* **num\_points** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of points in the sample set. + +**Returns** + +Matrices of (unit-norm) sample directions and sample points, one per row. Both matrices are 2D arrays of floats. + +**Raises** + +[**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.12)") – If not enough samples could be generated within the bounds. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)"), [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")] + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescent.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescent.md new file mode 100644 index 00000000000..e4cb77abde0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescent.md @@ -0,0 +1,466 @@ +--- +title: GradientDescent +description: API reference for qiskit.algorithms.optimizers.GradientDescent +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.GradientDescent +--- + +# GradientDescent + + + +`qiskit.algorithms.optimizers.GradientDescent(maxiter=100, learning_rate=0.01, tol=1e-07, callback=None, perturbation=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/gradient_descent.py "view source code") + +Bases: [`SteppableOptimizer`](qiskit.algorithms.optimizers.SteppableOptimizer "qiskit.algorithms.optimizers.steppable_optimizer.SteppableOptimizer") + +The gradient descent minimization routine. + +For a function $f$ and an initial point $\vec\theta_0$, the standard (or “vanilla”) gradient descent method is an iterative scheme to find the minimum $\vec\theta^*$ of $f$ by updating the parameters in the direction of the negative gradient of $f$ + +$$ +\vec\theta_{n+1} = \vec\theta_{n} - \eta_n \vec\nabla f(\vec\theta_{n}), +$$ + +for a small learning rate $\eta_n > 0$. + +You can either provide the analytic gradient $\vec\nabla f$ as `jac` in the [`minimize()`](#qiskit.algorithms.optimizers.GradientDescent.minimize "qiskit.algorithms.optimizers.GradientDescent.minimize") method, or, if you do not provide it, use a finite difference approximation of the gradient. To adapt the size of the perturbation in the finite difference gradients, set the `perturbation` property in the initializer. + +This optimizer supports a callback function. If provided in the initializer, the optimizer will call the callback in each iteration with the following information in this order: current number of function values, current parameters, current function value, norm of current gradient. + +**Examples** + +A minimum example that will use finite difference gradients with a default perturbation of 0.01 and a default learning rate of 0.01. + +```python +from qiskit.algorithms.optimizers import GradientDescent + +def f(x): + return (np.linalg.norm(x) - 1) ** 2 + +initial_point = np.array([1, 0.5, -0.2]) + +optimizer = GradientDescent(maxiter=100) + +result = optimizer.minimize(fun=fun, x0=initial_point) + +print(f"Found minimum {result.x} at a value" + "of {result.fun} using {result.nfev} evaluations.") +``` + +An example where the learning rate is an iterator and we supply the analytic gradient. Note how much faster this convergences (i.e. less `nfev`) compared to the previous example. + +```python +from qiskit.algorithms.optimizers import GradientDescent + +def learning_rate(): + power = 0.6 + constant_coeff = 0.1 + def powerlaw(): + n = 0 + while True: + yield constant_coeff * (n ** power) + n += 1 + + return powerlaw() + +def f(x): + return (np.linalg.norm(x) - 1) ** 2 + +def grad_f(x): + return 2 * (np.linalg.norm(x) - 1) * x / np.linalg.norm(x) + +initial_point = np.array([1, 0.5, -0.2]) + +optimizer = GradientDescent(maxiter=100, learning_rate=learning_rate) +result = optimizer.minimize(fun=fun, jac=grad_f, x0=initial_point) + +print(f"Found minimum {result.x} at a value" +"of {result.fun} using {result.nfev} evaluations.") +``` + +An other example where the evaluation of the function has a chance of failing. The user, with specific knowledge about his function can catch this errors and handle them before passing the result to the optimizer. + +> ```python +> import random +> import numpy as np +> from qiskit.algorithms.optimizers import GradientDescent +> +> def objective(x): +> if random.choice([True, False]): +> return None +> else: +> return (np.linalg.norm(x) - 1) ** 2 +> +> def grad(x): +> if random.choice([True, False]): +> return None +> else: +> return 2 * (np.linalg.norm(x) - 1) * x / np.linalg.norm(x) +> +> +> initial_point = np.random.normal(0, 1, size=(100,)) +> +> optimizer = GradientDescent(maxiter=20) +> optimizer.start(x0=initial_point, fun=objective, jac=grad) +> +> while optimizer.continue_condition(): +> ask_data = optimizer.ask() +> evaluated_gradient = None +> +> while evaluated_gradient is None: +> evaluated_gradient = grad(ask_data.x_center) +> optimizer.state.njev += 1 +> +> optmizer.state.nit += 1 +> +> tell_data = TellData(eval_jac=evaluated_gradient) +> optimizer.tell(ask_data=ask_data, tell_data=tell_data) +> +> result = optimizer.create_result() +> ``` + +Users that aren’t dealing with complicated functions and who are more familiar with step by step optimization algorithms can use the [`step()`](#qiskit.algorithms.optimizers.GradientDescent.step "qiskit.algorithms.optimizers.GradientDescent.step") method which wraps the [`ask()`](#qiskit.algorithms.optimizers.GradientDescent.ask "qiskit.algorithms.optimizers.GradientDescent.ask") and [`tell()`](#qiskit.algorithms.optimizers.GradientDescent.tell "qiskit.algorithms.optimizers.GradientDescent.tell") methods. In the same spirit the method [`minimize()`](#qiskit.algorithms.optimizers.GradientDescent.minimize "qiskit.algorithms.optimizers.GradientDescent.minimize") will optimize the function and return the result. + +To see other libraries that use this interface one can visit: [https://optuna.readthedocs.io/en/stable/tutorial/20\_recipes/009\_ask\_and\_tell.html](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/009_ask_and_tell.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of iterations. +* **learning\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | np.ndarray | Callable\[\[], Generator\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*, None, None]]*) – A constant, list, array or factory of generators yielding learning rates for the parameter updates. See the docstring for an example. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – If the norm of the parameter update is smaller than this threshold, the optimizer has converged. +* **perturbation** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – If no gradient is passed to [`minimize()`](#qiskit.algorithms.optimizers.GradientDescent.minimize "qiskit.algorithms.optimizers.GradientDescent.minimize") the gradient is approximated with a forward finite difference scheme with `perturbation` perturbation in both directions (defaults to 1e-2 if required). Ignored when we have an explicit function for the gradient. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `learning_rate` is an array and its length is less than `maxiter`. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### perturbation + +Returns the perturbation. + +This is the perturbation used in the finite difference gradient approximation. + + + +### setting + +Return setting + + + +### settings + + + +### state + +Return the current state of the optimizer. + + + +### tol + +Returns the tolerance of the optimizer. + +Any step with smaller stepsize than this value will stop the optimization. + +## Methods + +### ask + + + +`ask()` + +Returns an object with the data needed to evaluate the gradient. + +If this object contains a gradient function the gradient can be evaluated directly. Otherwise approximate it with a finite difference scheme. + +**Return type** + +[*AskData*](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.steppable_optimizer.AskData") + +### continue\_condition + + + +`continue_condition()` + +Condition that indicates the optimization process should come to an end. + +When the stepsize is smaller than the tolerance, the optimization process is considered finished. + +**Returns** + +`True` if the optimization process should continue, `False` otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### create\_result + + + +`create_result()` + +Creates a result of the optimization process. + +This result contains the best point, the best function value, the number of function/gradient evaluations and the number of iterations. + +**Returns** + +The result of the optimization process. + +**Return type** + +[*OptimizerResult*](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.optimizer.OptimizerResult") + +### evaluate + + + +`evaluate(ask_data)` + +Evaluates the gradient. + +It does so either by evaluating an analytic gradient or by approximating it with a finite difference scheme. It will either add `1` to the number of gradient evaluations or add `N+1` to the number of function evaluations (Where N is the dimension of the gradient). + +**Parameters** + +**ask\_data** ([*AskData*](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.steppable_optimizer.AskData")) – It contains the point where the gradient is to be evaluated and the gradient function or, in its absence, the objective function to perform a finite difference approximation. + +**Returns** + +The data containing the gradient evaluation. + +**Return type** + +[*TellData*](qiskit.algorithms.optimizers.TellData "qiskit.algorithms.optimizers.steppable_optimizer.TellData") + +### get\_support\_level + + + +`get_support_level()` + +Get the support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimizes the function. + +For well behaved functions the user can call this method to minimize a function. If the user wants more control on how to evaluate the function a custom loop can be created using [`ask()`](#qiskit.algorithms.optimizers.GradientDescent.ask "qiskit.algorithms.optimizers.GradientDescent.ask") and [`tell()`](#qiskit.algorithms.optimizers.GradientDescent.tell "qiskit.algorithms.optimizers.GradientDescent.tell") and evaluating the function manually. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Function to minimize. +* **x0** (*POINT*) – Initial point. +* **jac** (*Callable\[\[POINT], POINT] | None*) – Function to compute the gradient. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds of the search space. + +**Returns** + +Object containing the result of the optimization. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### start + + + +`start(fun, x0, jac=None, bounds=None)` + +Populates the state of the optimizer with the data provided and sets all the counters to 0. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Function to minimize. +* **x0** (*POINT*) – Initial point. +* **jac** (*Callable\[\[POINT], POINT] | None*) – Function to compute the gradient. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds of the search space. + +### step + + + +`step()` + +Performs one step in the optimization process. + +This method composes [`ask()`](#qiskit.algorithms.optimizers.GradientDescent.ask "qiskit.algorithms.optimizers.GradientDescent.ask"), [`evaluate()`](#qiskit.algorithms.optimizers.GradientDescent.evaluate "qiskit.algorithms.optimizers.GradientDescent.evaluate"), and [`tell()`](#qiskit.algorithms.optimizers.GradientDescent.tell "qiskit.algorithms.optimizers.GradientDescent.tell") to make a “step” in the optimization process. + +### tell + + + +`tell(ask_data, tell_data)` + +Updates `x` by an amount proportional to the learning rate and value of the gradient at that point. + +**Parameters** + +* **ask\_data** ([*AskData*](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.steppable_optimizer.AskData")) – The data used to evaluate the function. +* **tell\_data** ([*TellData*](qiskit.algorithms.optimizers.TellData "qiskit.algorithms.optimizers.steppable_optimizer.TellData")) – The data from the function evaluation. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the gradient passed doesn’t have the right dimension. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescentState.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescentState.md new file mode 100644 index 00000000000..1a51659e5f3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.GradientDescentState.md @@ -0,0 +1,88 @@ +--- +title: GradientDescentState +description: API reference for qiskit.algorithms.optimizers.GradientDescentState +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.GradientDescentState +--- + +# GradientDescentState + + + +`qiskit.algorithms.optimizers.GradientDescentState(x, fun, jac, nfev, njev, nit, stepsize, learning_rate)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/gradient_descent.py "view source code") + +Bases: [`OptimizerState`](qiskit.algorithms.optimizers.OptimizerState "qiskit.algorithms.optimizers.steppable_optimizer.OptimizerState") + +State of [`GradientDescent`](qiskit.algorithms.optimizers.GradientDescent "qiskit.algorithms.optimizers.GradientDescent"). + +Dataclass with all the information of an optimizer plus the learning\_rate and the stepsize. + +## Attributes + + + +### stepsize + +`float | None` + +Norm of the gradient on the last step. + + + +### learning\_rate + +`LearningRate` + +Learning rate at the current step of the optimization process. + +It behaves like a generator, (use `next(learning_rate)` to get the learning rate for the next step) but it can also return the current learning rate with `learning_rate.current`. + + + +### x + +`POINT` + +Current optimization parameters. + + + +### fun + +`Callable[[POINT], float] | None` + +Function being optimized. + + + +### jac + +`Callable[[POINT], POINT] | None` + +Jacobian of the function being optimized. + + + +### nfev + +`int | None` + +Number of function evaluations so far in the optimization. + + + +### njev + +`int | None` + +Number of jacobian evaluations so far in the opimization. + + + +### nit + +`int | None` + +Number of optimization steps performed so far in the optimization. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.IMFIL.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.IMFIL.md new file mode 100644 index 00000000000..5f76666454b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.IMFIL.md @@ -0,0 +1,221 @@ +--- +title: IMFIL +description: API reference for qiskit.algorithms.optimizers.IMFIL +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.IMFIL +--- + +# IMFIL + + + +`qiskit.algorithms.optimizers.IMFIL(maxiter=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/imfil.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +IMplicit FILtering algorithm. + +Implicit filtering is a way to solve bound-constrained optimization problems for which derivatives are not available. In comparison to methods that use interpolation to reconstruct the function and its higher derivatives, implicit filtering builds upon coordinate search followed by interpolation to get an approximate gradient. + +Uses skquant.opt installed with pip install scikit-quant. For further detail, please refer to [https://github.com/scikit-quant/scikit-quant](https://github.com/scikit-quant/scikit-quant) and [https://qat4chem.lbl.gov/software](https://qat4chem.lbl.gov/software). + +**Parameters** + +**maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – scikit-quant not installed + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Returns support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ISRES.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ISRES.md new file mode 100644 index 00000000000..35d441762c2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.ISRES.md @@ -0,0 +1,233 @@ +--- +title: ISRES +description: API reference for qiskit.algorithms.optimizers.ISRES +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.ISRES +--- + +# ISRES + + + +`qiskit.algorithms.optimizers.ISRES(max_evals=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nlopts/isres.py "view source code") + +Bases: `NLoptOptimizer` + +Improved Stochastic Ranking Evolution Strategy optimizer. + +Improved Stochastic Ranking Evolution Strategy (ISRES) is an algorithm for non-linearly constrained global optimization. It has heuristics to escape local optima, even though convergence to a global optima is not guaranteed. The evolution strategy is based on a combination of a mutation rule and differential variation. The fitness ranking is simply via the objective function for problems without nonlinear constraints. When nonlinear constraints are included, the [stochastic ranking proposed by Runarsson and Yao](https://notendur.hi.is/tpr/software/sres/Tec311r.pdf) is employed. This method supports arbitrary nonlinear inequality and equality constraints, in addition to the bound constraints. + +NLopt global optimizer, derivative-free. For further detail, please refer to [http://nlopt.readthedocs.io/en/latest/NLopt\_Algorithms/#isres-improved-stochastic-ranking-evolution-strategy](http://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#isres-improved-stochastic-ranking-evolution-strategy) + +**Parameters** + +**max\_evals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – NLopt library not installed. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_nlopt\_optimizer + + + +`get_nlopt_optimizer()` + +Return NLopt optimizer type + +**Return type** + +*NLoptOptimizerType* + +### get\_support\_level + + + +`get_support_level()` + +return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.L_BFGS_B.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.L_BFGS_B.md new file mode 100644 index 00000000000..cc4d6827eca --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.L_BFGS_B.md @@ -0,0 +1,230 @@ +--- +title: L_BFGS_B +description: API reference for qiskit.algorithms.optimizers.L_BFGS_B +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.L_BFGS_B +--- + + + +# L\_BFGS\_B + + + +`qiskit.algorithms.optimizers.L_BFGS_B(maxfun=15000, maxiter=15000, ftol=2.220446049250313e-15, iprint=-1, eps=1e-08, options=None, max_evals_grouped=1, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/l_bfgs_b.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Limited-memory BFGS Bound optimizer. + +The target goal of Limited-memory Broyden-Fletcher-Goldfarb-Shanno Bound (L-BFGS-B) is to minimize the value of a differentiable scalar function $f$. This optimizer is a quasi-Newton method, meaning that, in contrast to Newtons’s method, it does not require $f$’s Hessian (the matrix of $f$’s second derivatives) when attempting to compute $f$’s minimum value. + +Like BFGS, L-BFGS is an iterative method for solving unconstrained, non-linear optimization problems, but approximates BFGS using a limited amount of computer memory. L-BFGS starts with an initial estimate of the optimal value, and proceeds iteratively to refine that estimate with a sequence of better estimates. + +The derivatives of $f$ are used to identify the direction of steepest descent, and also to form an estimate of the Hessian matrix (second derivative) of $f$. L-BFGS-B extends L-BFGS to handle simple, per-variable bound constraints. + +Uses `scipy.optimize.fmin_l_bfgs_b`. For further detail, please refer to [https://docs.scipy.org/doc/scipy/reference/optimize.minimize-lbfgsb.html](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-lbfgsb.html) + +**Parameters** + +* **maxfun** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations. +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of iterations. +* **ftol** (*SupportsFloat*) – The iteration stops when $(f^k - f^{k+1}) / \max\{|f^k|, |f^{k+1}|,1\} \leq \text{ftol}$. +* **iprint** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Controls the frequency of output. `iprint < 0` means no output; `iprint = 0` print only one line at the last iteration; `0 < iprint < 99` print also $f$ and $|\text{proj} g|$ every iprint iterations; `iprint = 99` print details of every iteration except n-vectors; `iprint = 100` print also the changes of active set and final $x$; `iprint > 100` print details of every iteration including $x$ and $g$. +* **eps** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – If jac is approximated, use this value for the step size. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of default gradient evaluations performed simultaneously. +* **kwargs** – additional kwargs for `scipy.optimize.minimize`. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Minimizer.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Minimizer.md new file mode 100644 index 00000000000..c3a47c88765 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Minimizer.md @@ -0,0 +1,40 @@ +--- +title: Minimizer +description: API reference for qiskit.algorithms.optimizers.Minimizer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.Minimizer +--- + +# Minimizer + + + +`qiskit.algorithms.optimizers.Minimizer(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/optimizer.py "view source code") + +Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol "(in Python v3.12)") + +Callable Protocol for minimizer. + +This interface is based on [SciPy’s optimize module](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html). + +> This protocol defines a callable taking the following parameters: +> +> > **fun** +> > +> > The objective function to minimize (for example the energy in the case of the VQE). +> > +> > **x0** +> > +> > The initial point for the optimization. +> > +> > **jac** +> > +> > The gradient of the objective function. +> > +> > **bounds** +> > +> > Parameters bounds for the optimization. Note that these might not be supported by all optimizers. +> +> and which returns a minimization result object (either SciPy’s or Qiskit’s). + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NELDER_MEAD.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NELDER_MEAD.md new file mode 100644 index 00000000000..8bf81017151 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NELDER_MEAD.md @@ -0,0 +1,228 @@ +--- +title: NELDER_MEAD +description: API reference for qiskit.algorithms.optimizers.NELDER_MEAD +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.NELDER_MEAD +--- + + + +# NELDER\_MEAD + + + +`qiskit.algorithms.optimizers.NELDER_MEAD(maxiter=None, maxfev=1000, disp=False, xatol=0.0001, tol=None, adaptive=False, options=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nelder_mead.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Nelder-Mead optimizer. + +The Nelder-Mead algorithm performs unconstrained optimization; it ignores bounds or constraints. It is used to find the minimum or maximum of an objective function in a multidimensional space. It is based on the Simplex algorithm. Nelder-Mead is robust in many applications, especially when the first and second derivatives of the objective function are not known. + +However, if the numerical computation of the derivatives can be trusted to be accurate, other algorithms using the first and/or second derivatives information might be preferred to Nelder-Mead for their better performance in the general case, especially in consideration of the fact that the Nelder–Mead technique is a heuristic search method that can converge to non-stationary points. + +Uses scipy.optimize.minimize Nelder-Mead. For further detail, please refer to See [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Maximum allowed number of iterations. If both maxiter and maxfev are set, minimization will stop at the first reached. +* **maxfev** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. If both maxiter and maxfev are set, minimization will stop at the first reached. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to print convergence messages. +* **xatol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Absolute error in xopt between iterations that is acceptable for convergence. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Tolerance for termination. +* **adaptive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Adapt algorithm parameters to dimensionality of problem. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NFT.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NFT.md new file mode 100644 index 00000000000..ef9ae30b9c6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.NFT.md @@ -0,0 +1,232 @@ +--- +title: NFT +description: API reference for qiskit.algorithms.optimizers.NFT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.NFT +--- + +# NFT + + + +`qiskit.algorithms.optimizers.NFT(maxiter=None, maxfev=1024, disp=False, reset_interval=32, options=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/nft.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Nakanishi-Fujii-Todo algorithm. + +See [https://arxiv.org/abs/1903.12166](https://arxiv.org/abs/1903.12166) + +Built out using scipy framework, for details, please refer to [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html). + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Maximum number of iterations to perform. +* **maxfev** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations to perform. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – disp +* **reset\_interval** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The minimum estimates directly once in `reset_interval` times. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +**Notes** + +In this optimization method, the optimization function have to satisfy three conditions written in [\[1\]](#id2). + +**References** + +\[[1](#id1)] + +K. M. Nakanishi, K. Fujii, and S. Todo. 2019. Sequential minimal optimization for quantum-classical hybrid algorithms. arXiv preprint arXiv:1903.12166. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Optimizer.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Optimizer.md new file mode 100644 index 00000000000..e07f5219c90 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.Optimizer.md @@ -0,0 +1,221 @@ +--- +title: Optimizer +description: API reference for qiskit.algorithms.optimizers.Optimizer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.Optimizer +--- + +# Optimizer + + + +`qiskit.algorithms.optimizers.Optimizer`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/optimizer.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for optimization algorithm. + +Initialize the optimization algorithm, setting the support level for \_gradient\_support\_level, \_bound\_support\_level, \_initial\_point\_support\_level, and empty options. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +The optimizer settings in a dictionary format. + +The settings can for instance be used for JSON-serialization (if all settings are serializable, which e.g. doesn’t hold per default for callables), such that the optimizer object can be reconstructed as + +```python +settings = optimizer.settings +# JSON serialize and send to another server +optimizer = OptimizerClass(**settings) +``` + +## Methods + +### get\_support\_level + + + +`abstract get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`abstract minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerResult.md new file mode 100644 index 00000000000..66a6e2e79a6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerResult.md @@ -0,0 +1,70 @@ +--- +title: OptimizerResult +description: API reference for qiskit.algorithms.optimizers.OptimizerResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.OptimizerResult +--- + +# OptimizerResult + + + +`qiskit.algorithms.optimizers.OptimizerResult`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/optimizer.py "view source code") + +Bases: `AlgorithmResult` + +The result of an optimization routine. + +## Attributes + + + +### fun + +The final value of the minimization. + + + +### jac + +The final gradient of the minimization. + + + +### nfev + +The total number of function evaluations. + + + +### nit + +The total number of iterations. + + + +### njev + +The total number of gradient evaluations. + + + +### x + +The final point of the minimization. + +## Methods + +### combine + + + +`combine(result)` + +Any property from the argument that exists in the receiver is updated. :param result: Argument result with properties to be set. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Argument is None + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerState.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerState.md new file mode 100644 index 00000000000..b36bf8e5e1f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerState.md @@ -0,0 +1,70 @@ +--- +title: OptimizerState +description: API reference for qiskit.algorithms.optimizers.OptimizerState +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.OptimizerState +--- + +# OptimizerState + + + +`qiskit.algorithms.optimizers.OptimizerState(x, fun, jac, nfev, njev, nit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/steppable_optimizer.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Base class representing the state of the optimizer. + +This class stores the current state of the optimizer, given by the current point and (optionally) information like the function value, the gradient or the number of function evaluations. This dataclass can also store any other individual variables that change during the optimization. + +## Attributes + + + +### x + +`POINT` + +Current optimization parameters. + + + +### fun + +`Callable[[POINT], float] | None` + +Function being optimized. + + + +### jac + +`Callable[[POINT], POINT] | None` + +Jacobian of the function being optimized. + + + +### nfev + +`int | None` + +Number of function evaluations so far in the optimization. + + + +### njev + +`int | None` + +Number of jacobian evaluations so far in the opimization. + + + +### nit + +`int | None` + +Number of optimization steps performed so far in the optimization. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerSupportLevel.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerSupportLevel.md new file mode 100644 index 00000000000..ad2e1630865 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.OptimizerSupportLevel.md @@ -0,0 +1,44 @@ +--- +title: OptimizerSupportLevel +description: API reference for qiskit.algorithms.optimizers.OptimizerSupportLevel +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.OptimizerSupportLevel +--- + +# OptimizerSupportLevel + + + +`qiskit.algorithms.optimizers.OptimizerSupportLevel(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/optimizer.py "view source code") + +Bases: [`IntEnum`](https://docs.python.org/3/library/enum.html#enum.IntEnum "(in Python v3.12)") + +Support Level enum for features such as bounds, gradient and initial point + +## Attributes + + + +### not\_supported + +`= 0` + + + +### ignored + +`= 1` + + + +### supported + +`= 2` + + + +### required + +`= 3` + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.POWELL.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.POWELL.md new file mode 100644 index 00000000000..7a464de5968 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.POWELL.md @@ -0,0 +1,223 @@ +--- +title: POWELL +description: API reference for qiskit.algorithms.optimizers.POWELL +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.POWELL +--- + +# POWELL + + + +`qiskit.algorithms.optimizers.POWELL(maxiter=None, maxfev=1000, disp=False, xtol=0.0001, tol=None, options=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/powell.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Powell optimizer. + +The Powell algorithm performs unconstrained optimization; it ignores bounds or constraints. Powell is a *conjugate direction method*: it performs sequential one-dimensional minimization along each directional vector, which is updated at each iteration of the main minimization loop. The function being minimized need not be differentiable, and no derivatives are taken. + +Uses scipy.optimize.minimize Powell. For further detail, please refer to See [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Maximum allowed number of iterations. If both maxiter and maxfev are set, minimization will stop at the first reached. +* **maxfev** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum allowed number of function evaluations. If both maxiter and maxfev are set, minimization will stop at the first reached. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to print convergence messages. +* **xtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative error in solution xopt acceptable for convergence. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Tolerance for termination. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.P_BFGS.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.P_BFGS.md new file mode 100644 index 00000000000..301ba90656a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.P_BFGS.md @@ -0,0 +1,225 @@ +--- +title: P_BFGS +description: API reference for qiskit.algorithms.optimizers.P_BFGS +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.P_BFGS +--- + + + +# P\_BFGS + + + +`qiskit.algorithms.optimizers.P_BFGS(maxfun=1000, ftol=2.220446049250313e-15, iprint=-1, max_processes=None, options=None, max_evals_grouped=1, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/p_bfgs.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Parallelized Limited-memory BFGS optimizer. + +P-BFGS is a parallelized version of [`L_BFGS_B`](qiskit.algorithms.optimizers.L_BFGS_B "qiskit.algorithms.optimizers.L_BFGS_B") with which it shares the same parameters. P-BFGS can be useful when the target hardware is a quantum simulator running on a classical machine. This allows the multiple processes to use simulation to potentially reach a minimum faster. The parallelization may also help the optimizer avoid getting stuck at local optima. + +Uses scipy.optimize.fmin\_l\_bfgs\_b. For further detail, please refer to [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.fmin\_l\_bfgs\_b.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.fmin_l_bfgs_b.html) + +**Parameters** + +* **maxfun** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations. +* **ftol** (*SupportsFloat*) – The iteration stops when (f^k - f^\{k+1})/max\{|f^k|,|f^\{k+1}|,1} \<= ftol. +* **iprint** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Controls the frequency of output. iprint \< 0 means no output; iprint = 0 print only one line at the last iteration; 0 \< iprint \< 99 print also f and |proj g| every iprint iterations; iprint = 99 print details of every iteration except n-vectors; iprint = 100 print also the changes of active set and final x; iprint > 100 print details of every iteration including x and g. +* **max\_processes** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – maximum number of processes allowed, has a min. value of 1 if not None. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of default gradient evaluations performed simultaneously. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.QNSPSA.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.QNSPSA.md new file mode 100644 index 00000000000..995b4054ddf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.QNSPSA.md @@ -0,0 +1,416 @@ +--- +title: QNSPSA +description: API reference for qiskit.algorithms.optimizers.QNSPSA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.QNSPSA +--- + +# QNSPSA + + + +`qiskit.algorithms.optimizers.QNSPSA(fidelity, maxiter=100, blocking=True, allowed_increase=None, learning_rate=None, perturbation=None, resamplings=1, perturbation_dims=None, regularization=None, hessian_delay=0, lse_solver=None, initial_hessian=None, callback=None, termination_checker=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/qnspsa.py "view source code") + +Bases: [`SPSA`](qiskit.algorithms.optimizers.SPSA "qiskit.algorithms.optimizers.spsa.SPSA") + +The Quantum Natural SPSA (QN-SPSA) optimizer. + +The QN-SPSA optimizer \[1] is a stochastic optimizer that belongs to the family of gradient descent methods. This optimizer is based on SPSA but attempts to improve the convergence by sampling the **natural gradient** instead of the vanilla, first-order gradient. It achieves this by approximating Hessian of the `fidelity` of the ansatz circuit. + +Compared to natural gradients, which require $\mathcal{O}(d^2)$ expectation value evaluations for a circuit with $d$ parameters, QN-SPSA only requires $\mathcal{O}(1)$ and can therefore significantly speed up the natural gradient calculation by sacrificing some accuracy. Compared to SPSA, QN-SPSA requires 4 additional function evaluations of the fidelity. + +The stochastic approximation of the natural gradient can be systematically improved by increasing the number of `resamplings`. This leads to a Monte Carlo-style convergence to the exact, analytic value. + + + This component has some function that is normally random. If you want to reproduce behavior then you should set the random number generator seed in the algorithm\_globals (`qiskit.utils.algorithm_globals.random_seed = seed`). + + +**Examples** + +This short example runs QN-SPSA for the ground state calculation of the `Z ^ Z` observable where the ansatz is a `PauliTwoDesign` circuit. + +```python +import numpy as np +from qiskit.algorithms.optimizers import QNSPSA +from qiskit.circuit.library import PauliTwoDesign +from qiskit.primitives import Estimator, Sampler +from qiskit.quantum_info import Pauli + +# problem setup +ansatz = PauliTwoDesign(2, reps=1, seed=2) +observable = Pauli("ZZ") +initial_point = np.random.random(ansatz.num_parameters) + +# loss function +estimator = Estimator() + +def loss(x): + result = estimator.run([ansatz], [observable], [x]).result() + return np.real(result.values[0]) + +# fidelity for estimation of the geometric tensor +sampler = Sampler() +fidelity = QNSPSA.get_fidelity(ansatz, sampler) + +# run QN-SPSA +qnspsa = QNSPSA(fidelity, maxiter=300) +result = qnspsa.optimize(ansatz.num_parameters, loss, initial_point=initial_point) +``` + +This is a legacy version solving the same problem but using Qiskit Opflow instead of the Qiskit Primitives. Note however, that this usage is deprecated. + +```python +import numpy as np +from qiskit.algorithms.optimizers import QNSPSA +from qiskit.circuit.library import PauliTwoDesign +from qiskit.opflow import Z, StateFn + +ansatz = PauliTwoDesign(2, reps=1, seed=2) +observable = Z ^ Z +initial_point = np.random.random(ansatz.num_parameters) + +def loss(x): + bound = ansatz.assign_parameters(x) + return np.real((StateFn(observable, is_measurement=True) @ StateFn(bound)).eval()) + +fidelity = QNSPSA.get_fidelity(ansatz) +qnspsa = QNSPSA(fidelity, maxiter=300) +result = qnspsa.optimize(ansatz.num_parameters, loss, initial_point=initial_point) +``` + +**References** + +\[1] J. Gacon et al, “Simultaneous Perturbation Stochastic Approximation of the Quantum Fisher Information”, [arXiv:2103.09232](https://arxiv.org/abs/2103.09232) + +**Parameters** + +* **fidelity** (*FIDELITY*) – A function to compute the fidelity of the ansatz state with itself for two different sets of parameters. +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of iterations. Note that this is not the maximal number of function evaluations. +* **blocking** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, only accepts updates that improve the loss (up to some allowed increase, see next argument). +* **allowed\_increase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – If `blocking` is `True`, this argument determines by how much the loss can increase with the proposed parameters and still be accepted. If `None`, the allowed increases is calibrated automatically to be twice the approximated standard deviation of the loss function. +* **learning\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| Callable\[\[], Iterator] | None*) – The update step is the learning rate is multiplied with the gradient. If the learning rate is a float, it remains constant over the course of the optimization. It can also be a callable returning an iterator which yields the learning rates for each optimization step. If `learning_rate` is set `perturbation` must also be provided. +* **perturbation** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| Callable\[\[], Iterator] | None*) – Specifies the magnitude of the perturbation for the finite difference approximation of the gradients. Can be either a float or a generator yielding the perturbation magnitudes per step. If `perturbation` is set `learning_rate` must also be provided. +* **resamplings** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The number of times the gradient (and Hessian) is sampled using a random direction to construct a gradient estimate. Per default the gradient is estimated using only one random direction. If an integer, all iterations use the same number of resamplings. If a dictionary, this is interpreted as `{iteration: number of resamplings per iteration}`. +* **perturbation\_dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of perturbed dimensions. Per default, all dimensions are perturbed, but a smaller, fixed number can be perturbed. If set, the perturbed dimensions are chosen uniformly at random. +* **regularization** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – To ensure the preconditioner is symmetric and positive definite, the identity times a small coefficient is added to it. This generator yields that coefficient. +* **hessian\_delay** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Start multiplying the gradient with the inverse Hessian only after a certain number of iterations. The Hessian is still evaluated and therefore this argument can be useful to first get a stable average over the last iterations before using it as preconditioner. +* **lse\_solver** (*Callable\[\[np.ndarray, np.ndarray], np.ndarray] | None*) – The method to solve for the inverse of the Hessian. Per default an exact LSE solver is used, but can e.g. be overwritten by a minimization routine. +* **initial\_hessian** (*np.ndarray | None*) – The initial guess for the Hessian. By default the identity matrix is used. +* **callback** (*CALLBACK | None*) – A callback function passed information in each iteration step. The information is, in this order: the parameters, the function value, the number of function evaluations, the stepsize, whether the step was accepted. +* **termination\_checker** (*TERMINATIONCHECKER | None*) – A callback function executed at the end of each iteration step. The arguments are, in this order: the parameters, the function value, the number of function evaluations, the stepsize, whether the step was accepted. If the callback returns True, the optimization is terminated. To prevent additional evaluations of the objective method, if the objective has not yet been evaluated, the objective is estimated by taking the mean of the objective evaluations used in the estimate of the gradient. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +The optimizer settings in a dictionary format. + +## Methods + +### calibrate + + + +`static calibrate(loss, initial_point, c=0.2, stability_constant=0, target_magnitude=None, alpha=0.602, gamma=0.101, modelspace=False, max_evals_grouped=1)` + +Calibrate SPSA parameters with a powerseries as learning rate and perturbation coeffs. + +The powerseries are: + +$$ +a_k = \frac{a}{(A + k + 1)^\alpha}, c_k = \frac{c}{(k + 1)^\gamma} +$$ + +**Parameters** + +* **loss** (*Callable\[\[np.ndarray],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The loss function. +* **initial\_point** (*np.ndarray*) – The initial guess of the iteration. +* **c** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The initial perturbation magnitude. +* **stability\_constant** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The value of A. +* **target\_magnitude** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The target magnitude for the first update step, defaults to $2\pi / 10$. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The exponent of the learning rate powerseries. +* **gamma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The exponent of the perturbation powerseries. +* **modelspace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the target magnitude is the difference of parameter values or function values (= model space). +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of grouped evaluations supported by the loss function. Defaults to 1, i.e. no grouping. + +**Returns** + +**A tuple of powerseries generators, the first one for the** + +learning rate and the second one for the perturbation. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")(generator, generator) + +### estimate\_stddev + + + +`static estimate_stddev(loss, initial_point, avg=25, max_evals_grouped=1)` + +Estimate the standard deviation of the loss function. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### get\_fidelity + + + +`static get_fidelity(circuit, backend=None, expectation=None, *, sampler=None)` + +Get a function to compute the fidelity of `circuit` with itself. + + + Using this function with a backend and expectation converter is pending deprecation, instead pass a Qiskit Primitive sampler, such as [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler"). The sampler can be passed as keyword argument or, positionally, as second argument. + + +Let `circuit` be a parameterized quantum circuit performing the operation $U(\theta)$ given a set of parameters $\theta$. Then this method returns a function to evaluate + +$$ +F(\theta, \phi) = \big|\langle 0 | U^\dagger(\theta) U(\phi) |0\rangle \big|^2. +$$ + +The output of this function can be used as input for the `fidelity` to the [`QNSPSA`](#qiskit.algorithms.optimizers.QNSPSA "qiskit.algorithms.optimizers.QNSPSA") optimizer. + + + `qiskit.algorithms.optimizers.qnspsa.QNSPSA.get_fidelity()`’s argument `expectation` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + + + `qiskit.algorithms.optimizers.qnspsa.QNSPSA.get_fidelity()`’s argument `backend` is deprecated as of qiskit-terra 0.24.0. It will be removed no earlier than 3 months after the release date. See [https://qisk.it/algo\_migration](https://qisk.it/algo_migration) for a migration guide. + + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The circuit preparing the parameterized ansatz. +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend") *|*[*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") *| None*) – Deprecated. A backend of quantum instance to evaluate the circuits. If None, plain matrix multiplication will be used. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase") *| None*) – Deprecated. An expectation converter to specify how the expected value is computed. If a shot-based readout is used this should be set to `PauliExpectation`. +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") *| None*) – A sampler primitive to sample from a quantum state. + +**Returns** + +A handle to the function $F$. + +**Return type** + +Callable\[\[np.ndarray, np.ndarray], [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### get\_support\_level + + + +`get_support_level()` + +Get the support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### optimize + + + +`optimize(num_vars, objective_function, gradient_function=None, variable_bounds=None, initial_point=None)` + +Perform optimization. + + + The method `qiskit.algorithms.optimizers.spsa.SPSA.optimize()` is deprecated as of qiskit-terra 0.21.0. It will be removed no earlier than 3 months after the release date. Instead, use `SPSA.minimize` as a replacement, which supports the same arguments but follows the interface of scipy.optimize and returns a complete result object containing additional information. + + +**Parameters** + +* **num\_vars** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of parameters to be optimized. +* **objective\_function** (*callable*) – A function that computes the objective function. +* **gradient\_function** (*callable*) – Not supported for SPSA. +* **variable\_bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[(*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*)]*) – Not supported for SPSA. +* **initial\_point** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Initial point. + +**Returns** + +**point, value, nfev** + +point: is a 1D numpy.ndarray\[float] containing the solution value: is a float with the objective function value nfev: number of objective function calls made if available or None + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SLSQP.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SLSQP.md new file mode 100644 index 00000000000..c88001815d6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SLSQP.md @@ -0,0 +1,226 @@ +--- +title: SLSQP +description: API reference for qiskit.algorithms.optimizers.SLSQP +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.SLSQP +--- + +# SLSQP + + + +`qiskit.algorithms.optimizers.SLSQP(maxiter=100, disp=False, ftol=1e-06, tol=None, eps=1.4901161193847656e-08, options=None, max_evals_grouped=1, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/slsqp.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Sequential Least SQuares Programming optimizer. + +SLSQP minimizes a function of several variables with any combination of bounds, equality and inequality constraints. The method wraps the SLSQP Optimization subroutine originally implemented by Dieter Kraft. + +SLSQP is ideal for mathematical problems for which the objective function and the constraints are twice continuously differentiable. Note that the wrapper handles infinite values in bounds by converting them into large floating values. + +Uses scipy.optimize.minimize SLSQP. For further detail, please refer to See [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of iterations. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to print convergence messages. +* **ftol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Precision goal for the value of f in the stopping criterion. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Tolerance for termination. +* **eps** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Step size used for numerical approximation of the Jacobian. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of default gradient evaluations performed simultaneously. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SNOBFIT.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SNOBFIT.md new file mode 100644 index 00000000000..aa863c5332e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SNOBFIT.md @@ -0,0 +1,225 @@ +--- +title: SNOBFIT +description: API reference for qiskit.algorithms.optimizers.SNOBFIT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.SNOBFIT +--- + +# SNOBFIT + + + +`qiskit.algorithms.optimizers.SNOBFIT(maxiter=1000, maxfail=10, maxmp=None, verbose=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/snobfit.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Stable Noisy Optimization by Branch and FIT algorithm. + +SnobFit is used for the optimization of derivative-free, noisy objective functions providing robust and fast solutions of problems with continuous variables varying within bound. + +Uses skquant.opt installed with pip install scikit-quant. For further detail, please refer to [https://github.com/scikit-quant/scikit-quant](https://github.com/scikit-quant/scikit-quant) and [https://qat4chem.lbl.gov/software](https://qat4chem.lbl.gov/software). + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluations. +* **maxmp** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of model points requested for the local fit. Default = 2 \* number of parameters + 6 set to this value when None. +* **maxfail** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of failures to improve the solution. Stops the algorithm after maxfail is reached. +* **verbose** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Provide verbose (debugging) output. + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – scikit-quant or SQSnobFit not installed +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If NumPy 1.24.0 or above is installed. See [https://github.com/scikit-quant/scikit-quant/issues/24](https://github.com/scikit-quant/scikit-quant/issues/24) for more details. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Returns support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SPSA.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SPSA.md new file mode 100644 index 00000000000..b54d9c6e73d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SPSA.md @@ -0,0 +1,399 @@ +--- +title: SPSA +description: API reference for qiskit.algorithms.optimizers.SPSA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.SPSA +--- + +# SPSA + + + +`qiskit.algorithms.optimizers.SPSA(maxiter=100, blocking=False, allowed_increase=None, trust_region=False, learning_rate=None, perturbation=None, last_avg=1, resamplings=1, perturbation_dims=None, second_order=False, regularization=None, hessian_delay=0, lse_solver=None, initial_hessian=None, callback=None, termination_checker=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/spsa.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Simultaneous Perturbation Stochastic Approximation (SPSA) optimizer. + +SPSA \[1] is an gradient descent method for optimizing systems with multiple unknown parameters. As an optimization method, it is appropriately suited to large-scale population models, adaptive modeling, and simulation optimization. + + + Many examples are presented at the [SPSA Web site](http://www.jhuapl.edu/SPSA). + + +The main feature of SPSA is the stochastic gradient approximation, which requires only two measurements of the objective function, regardless of the dimension of the optimization problem. + +Additionally to standard, first-order SPSA, where only gradient information is used, this implementation also allows second-order SPSA (2-SPSA) \[2]. In 2-SPSA we also estimate the Hessian of the loss with a stochastic approximation and multiply the gradient with the inverse Hessian to take local curvature into account and improve convergence. Notably this Hessian estimate requires only a constant number of function evaluations unlike an exact evaluation of the Hessian, which scales quadratically in the number of function evaluations. + + + SPSA can be used in the presence of noise, and it is therefore indicated in situations involving measurement uncertainty on a quantum computation when finding a minimum. If you are executing a variational algorithm using an OpenQASM simulator or a real device, SPSA would be the most recommended choice among the optimizers provided here. + + +The optimization process can includes a calibration phase if neither the `learning_rate` nor `perturbation` is provided, which requires additional functional evaluations. (Note that either both or none must be set.) For further details on the automatic calibration, please refer to the supplementary information section IV. of \[3]. + + + This component has some function that is normally random. If you want to reproduce behavior then you should set the random number generator seed in the algorithm\_globals (`qiskit.utils.algorithm_globals.random_seed = seed`). + + +**Examples** + +This short example runs SPSA for the ground state calculation of the `Z ^ Z` observable where the ansatz is a `PauliTwoDesign` circuit. + +```python +import numpy as np +from qiskit.algorithms.optimizers import SPSA +from qiskit.circuit.library import PauliTwoDesign +from qiskit.opflow import Z, StateFn + +ansatz = PauliTwoDesign(2, reps=1, seed=2) +observable = Z ^ Z +initial_point = np.random.random(ansatz.num_parameters) + +def loss(x): + bound = ansatz.assign_parameters(x) + return np.real((StateFn(observable, is_measurement=True) @ StateFn(bound)).eval()) + +spsa = SPSA(maxiter=300) +result = spsa.optimize(ansatz.num_parameters, loss, initial_point=initial_point) +``` + +To use the Hessian information, i.e. 2-SPSA, you can add second\_order=True to the initializer of the SPSA class, the rest of the code remains the same. + +```python +two_spsa = SPSA(maxiter=300, second_order=True) +result = two_spsa.optimize(ansatz.num_parameters, loss, initial_point=initial_point) +``` + +The termination\_checker can be used to implement a custom termination criterion. + +```python +import numpy as np +from qiskit.algorithms.optimizers import SPSA + +def objective(x): + return np.linalg.norm(x) + .04*np.random.rand(1) + +class TerminationChecker: + + def __init__(self, N : int): + self.N = N + self.values = [] + + def __call__(self, nfev, parameters, value, stepsize, accepted) -> bool: + self.values.append(value) + + if len(self.values) > self.N: + last_values = self.values[-self.N:] + pp = np.polyfit(range(self.N), last_values, 1) + slope = pp[0] / self.N + + if slope > 0: + return True + return False + +spsa = SPSA(maxiter=200, termination_checker=TerminationChecker(10)) +parameters, value, niter = spsa.optimize(2, objective, initial_point=[0.5, 0.5]) +print(f'SPSA completed after {niter} iterations') +``` + +**References** + +\[1]: J. C. Spall (1998). An Overview of the Simultaneous Perturbation Method for Efficient Optimization, Johns Hopkins APL Technical Digest, 19(4), 482–492. [Online at jhuapl.edu.](https://www.jhuapl.edu/SPSA/PDF-SPSA/Spall_An_Overview.PDF) + +\[2]: J. C. Spall (1997). Accelerated second-order stochastic optimization using only function measurements, Proceedings of the 36th IEEE Conference on Decision and Control, 1417-1424 vol.2. [Online at IEEE.org.](https://ieeexplore.ieee.org/document/657661) + +\[3]: A. Kandala et al. (2017). Hardware-efficient Variational Quantum Eigensolver for Small Molecules and Quantum Magnets. Nature 549, pages242–246(2017). [arXiv:1704.05018v2](https://arxiv.org/pdf/1704.05018v2.pdf#section*.11) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of iterations. Note that this is not the maximal number of function evaluations. +* **blocking** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, only accepts updates that improve the loss (up to some allowed increase, see next argument). +* **allowed\_increase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – If `blocking` is `True`, this argument determines by how much the loss can increase with the proposed parameters and still be accepted. If `None`, the allowed increases is calibrated automatically to be twice the approximated standard deviation of the loss function. +* **trust\_region** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, restricts the norm of the update step to be $\leq 1$. +* **learning\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| np.ndarray | Callable\[\[], Iterator] | None*) – The update step is the learning rate is multiplied with the gradient. If the learning rate is a float, it remains constant over the course of the optimization. If a NumPy array, the $i$-th element is the learning rate for the $i$-th iteration. It can also be a callable returning an iterator which yields the learning rates for each optimization step. If `learning_rate` is set `perturbation` must also be provided. +* **perturbation** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| np.ndarray | Callable\[\[], Iterator] | None*) – Specifies the magnitude of the perturbation for the finite difference approximation of the gradients. See `learning_rate` for the supported types. If `perturbation` is set `learning_rate` must also be provided. +* **last\_avg** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Return the average of the `last_avg` parameters instead of just the last parameter values. +* **resamplings** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The number of times the gradient (and Hessian) is sampled using a random direction to construct a gradient estimate. Per default the gradient is estimated using only one random direction. If an integer, all iterations use the same number of resamplings. If a dictionary, this is interpreted as `{iteration: number of resamplings per iteration}`. +* **perturbation\_dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of perturbed dimensions. Per default, all dimensions are perturbed, but a smaller, fixed number can be perturbed. If set, the perturbed dimensions are chosen uniformly at random. +* **second\_order** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, use 2-SPSA instead of SPSA. In 2-SPSA, the Hessian is estimated additionally to the gradient, and the gradient is preconditioned with the inverse of the Hessian to improve convergence. +* **regularization** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – To ensure the preconditioner is symmetric and positive definite, the identity times a small coefficient is added to it. This generator yields that coefficient. +* **hessian\_delay** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Start multiplying the gradient with the inverse Hessian only after a certain number of iterations. The Hessian is still evaluated and therefore this argument can be useful to first get a stable average over the last iterations before using it as preconditioner. +* **lse\_solver** (*Callable\[\[np.ndarray, np.ndarray], np.ndarray] | None*) – The method to solve for the inverse of the Hessian. Per default an exact LSE solver is used, but can e.g. be overwritten by a minimization routine. +* **initial\_hessian** (*np.ndarray | None*) – The initial guess for the Hessian. By default the identity matrix is used. +* **callback** (*CALLBACK | None*) – A callback function passed information in each iteration step. The information is, in this order: the number of function evaluations, the parameters, the function value, the stepsize, whether the step was accepted. +* **termination\_checker** (*TERMINATIONCHECKER | None*) – A callback function executed at the end of each iteration step. The arguments are, in this order: the parameters, the function value, the number of function evaluations, the stepsize, whether the step was accepted. If the callback returns True, the optimization is terminated. To prevent additional evaluations of the objective method, if the objective has not yet been evaluated, the objective is estimated by taking the mean of the objective evaluations used in the estimate of the gradient. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `learning_rate` or `perturbation` is an array with less elements than the number of iterations. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### calibrate + + + +`static calibrate(loss, initial_point, c=0.2, stability_constant=0, target_magnitude=None, alpha=0.602, gamma=0.101, modelspace=False, max_evals_grouped=1)` + +Calibrate SPSA parameters with a powerseries as learning rate and perturbation coeffs. + +The powerseries are: + +$$ +a_k = \frac{a}{(A + k + 1)^\alpha}, c_k = \frac{c}{(k + 1)^\gamma} +$$ + +**Parameters** + +* **loss** (*Callable\[\[np.ndarray],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The loss function. +* **initial\_point** (*np.ndarray*) – The initial guess of the iteration. +* **c** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The initial perturbation magnitude. +* **stability\_constant** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The value of A. +* **target\_magnitude** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The target magnitude for the first update step, defaults to $2\pi / 10$. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The exponent of the learning rate powerseries. +* **gamma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The exponent of the perturbation powerseries. +* **modelspace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the target magnitude is the difference of parameter values or function values (= model space). +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of grouped evaluations supported by the loss function. Defaults to 1, i.e. no grouping. + +**Returns** + +**A tuple of powerseries generators, the first one for the** + +learning rate and the second one for the perturbation. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")(generator, generator) + +### estimate\_stddev + + + +`static estimate_stddev(loss, initial_point, avg=25, max_evals_grouped=1)` + +Estimate the standard deviation of the loss function. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### get\_support\_level + + + +`get_support_level()` + +Get the support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### optimize + + + +`optimize(num_vars, objective_function, gradient_function=None, variable_bounds=None, initial_point=None)` + +Perform optimization. + + + The method `qiskit.algorithms.optimizers.spsa.SPSA.optimize()` is deprecated as of qiskit-terra 0.21.0. It will be removed no earlier than 3 months after the release date. Instead, use `SPSA.minimize` as a replacement, which supports the same arguments but follows the interface of scipy.optimize and returns a complete result object containing additional information. + + +**Parameters** + +* **num\_vars** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of parameters to be optimized. +* **objective\_function** (*callable*) – A function that computes the objective function. +* **gradient\_function** (*callable*) – Not supported for SPSA. +* **variable\_bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[(*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*)]*) – Not supported for SPSA. +* **initial\_point** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Initial point. + +**Returns** + +**point, value, nfev** + +point: is a 1D numpy.ndarray\[float] containing the solution value: is a float with the objective function value nfev: number of objective function calls made if available or None + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SciPyOptimizer.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SciPyOptimizer.md new file mode 100644 index 00000000000..ee2ab0af1a6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SciPyOptimizer.md @@ -0,0 +1,218 @@ +--- +title: SciPyOptimizer +description: API reference for qiskit.algorithms.optimizers.SciPyOptimizer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.SciPyOptimizer +--- + +# SciPyOptimizer + + + +`qiskit.algorithms.optimizers.SciPyOptimizer(method, options=None, max_evals_grouped=1, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/scipy_optimizer.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +A general Qiskit Optimizer wrapping scipy.optimize.minimize. + +For further detail, please refer to [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| Callable*) – Type of solver. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – A dictionary of solver options. +* **kwargs** – additional kwargs for scipy.optimize.minimize. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of default gradient evaluations performed simultaneously. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SteppableOptimizer.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SteppableOptimizer.md new file mode 100644 index 00000000000..e121b675a63 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.SteppableOptimizer.md @@ -0,0 +1,396 @@ +--- +title: SteppableOptimizer +description: API reference for qiskit.algorithms.optimizers.SteppableOptimizer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.SteppableOptimizer +--- + +# SteppableOptimizer + + + +`qiskit.algorithms.optimizers.SteppableOptimizer(maxiter=100)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/steppable_optimizer.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Base class for a steppable optimizer. + +This family of optimizers uses the [ask and tell interface](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/009_ask_and_tell.html). When using this interface the user has to call [`ask()`](#qiskit.algorithms.optimizers.SteppableOptimizer.ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask") to get information about how to evaluate the function (we are asking the optimizer about how to do the evaluation). This information is typically the next points at which the function is evaluated, but depending on the optimizer it can also determine whether to evaluate the function or its gradient. Once the function has been evaluated, the user calls the method `tell()` to tell the optimizer what the result of the function evaluation(s) is. The optimizer then updates its state accordingly and the user can decide whether to stop the optimization process or to repeat a step. + +This interface is more customizable, and allows the user to have full control over the evaluation of the function. + +**Examples** + +An example where the evaluation of the function has a chance of failing. The user, with specific knowledge about his function can catch this errors and handle them before passing the result to the optimizer. + +```python +import random +import numpy as np +from qiskit.algorithms.optimizers import GradientDescent + +def objective(x): + if random.choice([True, False]): + return None + else: + return (np.linalg.norm(x) - 1) ** 2 + +def grad(x): + if random.choice([True, False]): + return None + else: + return 2 * (np.linalg.norm(x) - 1) * x / np.linalg.norm(x) + + +initial_point = np.random.normal(0, 1, size=(100,)) + +optimizer = GradientDescent(maxiter=20) +optimizer.start(x0=initial_point, fun=objective, jac=grad) + +while optimizer.continue_condition(): + ask_data = optimizer.ask() + evaluated_gradient = None + + while evaluated_gradient is None: + evaluated_gradient = grad(ask_data.x_center) + optimizer.state.njev += 1 + + optmizer.state.nit += 1 + + cf = TellData(eval_jac=evaluated_gradient) + optimizer.tell(ask_data=ask_data, tell_data=tell_data) + +result = optimizer.create_result() +``` + +Users that aren’t dealing with complicated functions and who are more familiar with step by step optimization algorithms can use the [`step()`](#qiskit.algorithms.optimizers.SteppableOptimizer.step "qiskit.algorithms.optimizers.SteppableOptimizer.step") method which wraps the [`ask()`](#qiskit.algorithms.optimizers.SteppableOptimizer.ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask") and [`tell()`](#qiskit.algorithms.optimizers.SteppableOptimizer.tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell") methods. In the same spirit the method [`minimize()`](#qiskit.algorithms.optimizers.SteppableOptimizer.minimize "qiskit.algorithms.optimizers.SteppableOptimizer.minimize") will optimize the function and return the result. + +To see other libraries that use this interface one can visit: [https://optuna.readthedocs.io/en/stable/tutorial/20\_recipes/009\_ask\_and\_tell.html](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/009_ask_and_tell.html) + +**Parameters** + +**maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of steps in the optimization process before ending the loop. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +The optimizer settings in a dictionary format. + +The settings can for instance be used for JSON-serialization (if all settings are serializable, which e.g. doesn’t hold per default for callables), such that the optimizer object can be reconstructed as + +```python +settings = optimizer.settings +# JSON serialize and send to another server +optimizer = OptimizerClass(**settings) +``` + + + +### state + +Return the current state of the optimizer. + +## Methods + +### ask + + + +`ask()` + +Ask the optimizer for a set of points to evaluate. + +This method asks the optimizer which are the next points to evaluate. These points can, e.g., correspond to function values and/or its derivative. It may also correspond to variables that let the user infer which points to evaluate. It is the first method inside of a [`step()`](#qiskit.algorithms.optimizers.SteppableOptimizer.step "qiskit.algorithms.optimizers.SteppableOptimizer.step") in the optimization process. + +**Returns** + +An object containing the data needed to make the function evaluation to advance the optimization process. + +**Return type** + +[*AskData*](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.steppable_optimizer.AskData") + +### continue\_condition + + + +`continue_condition()` + +Condition that indicates the optimization process should continue. + +**Returns** + +`True` if the optimization process should continue, `False` otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### create\_result + + + +`abstract create_result()` + +Returns the result of the optimization. + +All the information needed to create such a result should be stored in the optimizer state and will typically contain the best point found, the function value and gradient at that point, the number of function and gradient evaluation and the number of iterations in the optimization. + +**Returns** + +The result of the optimization process. + +**Return type** + +[*OptimizerResult*](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.optimizer.OptimizerResult") + +### evaluate + + + +`abstract evaluate(ask_data)` + +Evaluates the function according to the instructions contained in `ask_data`. + +If the user decides to use [`step()`](#qiskit.algorithms.optimizers.SteppableOptimizer.step "qiskit.algorithms.optimizers.SteppableOptimizer.step") instead of [`ask()`](#qiskit.algorithms.optimizers.SteppableOptimizer.ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask") and [`tell()`](#qiskit.algorithms.optimizers.SteppableOptimizer.tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell") this function will contain the logic on how to evaluate the function. + +**Parameters** + +**ask\_data** ([*AskData*](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.steppable_optimizer.AskData")) – Contains the information on how to do the evaluation. + +**Returns** + +Data of all relevant information about the function evaluation. + +**Return type** + +[*TellData*](qiskit.algorithms.optimizers.TellData "qiskit.algorithms.optimizers.steppable_optimizer.TellData") + +### get\_support\_level + + + +`abstract get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimizes the function. + +For well behaved functions the user can call this method to minimize a function. If the user wants more control on how to evaluate the function a custom loop can be created using [`ask()`](#qiskit.algorithms.optimizers.SteppableOptimizer.ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask") and [`tell()`](#qiskit.algorithms.optimizers.SteppableOptimizer.tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell") and evaluating the function manually. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Function to minimize. +* **x0** (*POINT*) – Initial point. +* **jac** (*Callable\[\[POINT], POINT] | None*) – Function to compute the gradient. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds of the search space. + +**Returns** + +Object containing the result of the optimization. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### start + + + +`abstract start(fun, x0, jac=None, bounds=None)` + +Populates the state of the optimizer with the data provided and sets all the counters to 0. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Function to minimize. +* **x0** (*POINT*) – Initial point. +* **jac** (*Callable\[\[POINT], POINT] | None*) – Function to compute the gradient. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds of the search space. + +### step + + + +`step()` + +Performs one step in the optimization process. + +This method composes [`ask()`](#qiskit.algorithms.optimizers.SteppableOptimizer.ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask"), [`evaluate()`](#qiskit.algorithms.optimizers.SteppableOptimizer.evaluate "qiskit.algorithms.optimizers.SteppableOptimizer.evaluate"), and [`tell()`](#qiskit.algorithms.optimizers.SteppableOptimizer.tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell") to make a “step” in the optimization process. + +### tell + + + +`tell(ask_data, tell_data)` + +Updates the optimization state using the results of the function evaluation. + +A canonical optimization example using [`ask()`](#qiskit.algorithms.optimizers.SteppableOptimizer.ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask") and [`tell()`](#qiskit.algorithms.optimizers.SteppableOptimizer.tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell") can be seen in [`step()`](#qiskit.algorithms.optimizers.SteppableOptimizer.step "qiskit.algorithms.optimizers.SteppableOptimizer.step"). + +**Parameters** + +* **ask\_data** ([*AskData*](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.steppable_optimizer.AskData")) – Contains the information on how the evaluation was done. +* **tell\_data** ([*TellData*](qiskit.algorithms.optimizers.TellData "qiskit.algorithms.optimizers.steppable_optimizer.TellData")) – Contains all relevant information about the evaluation of the objective function. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TNC.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TNC.md new file mode 100644 index 00000000000..4d9718336d5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TNC.md @@ -0,0 +1,227 @@ +--- +title: TNC +description: API reference for qiskit.algorithms.optimizers.TNC +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.TNC +--- + +# TNC + + + +`qiskit.algorithms.optimizers.TNC(maxiter=100, disp=False, accuracy=0, ftol=-1, xtol=-1, gtol=-1, tol=None, eps=1e-08, options=None, max_evals_grouped=1, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/tnc.py "view source code") + +Bases: [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.scipy_optimizer.SciPyOptimizer") + +Truncated Newton (TNC) optimizer. + +TNC uses a truncated Newton algorithm to minimize a function with variables subject to bounds. This algorithm uses gradient information; it is also called Newton Conjugate-Gradient. It differs from the [`CG`](qiskit.algorithms.optimizers.CG "qiskit.algorithms.optimizers.CG") method as it wraps a C implementation and allows each variable to be given upper and lower bounds. + +Uses scipy.optimize.minimize TNC For further detail, please refer to See [https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html) + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of function evaluation. +* **disp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True to print convergence messages. +* **accuracy** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative precision for finite difference calculations. If \<= machine\_precision, set to sqrt(machine\_precision). Defaults to 0. +* **ftol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Precision goal for the value of f in the stopping criterion. If ftol \< 0.0, ftol is set to 0.0 defaults to -1. +* **xtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Precision goal for the value of x in the stopping criterion (after applying x scaling factors). If xtol \< 0.0, xtol is set to sqrt(machine\_precision). Defaults to -1. +* **gtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Precision goal for the value of the projected gradient in the stopping criterion (after applying x scaling factors). If gtol \< 0.0, gtol is set to 1e-2 \* sqrt(accuracy). Setting it to 0.0 is not recommended. Defaults to -1. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Tolerance for termination. +* **eps** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Step size used for numerical approximation of the Jacobian. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – A dictionary of solver options. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Max number of default gradient evaluations performed simultaneously. +* **kwargs** – additional kwargs for scipy.optimize.minimize. + +## Attributes + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### setting + +Return setting + + + +### settings + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Return support level dictionary + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TellData.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TellData.md new file mode 100644 index 00000000000..18be7da16fd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.TellData.md @@ -0,0 +1,41 @@ +--- +title: TellData +description: API reference for qiskit.algorithms.optimizers.TellData +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.TellData +--- + +# TellData + + + +`qiskit.algorithms.optimizers.TellData(eval_fun=None, eval_jac=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/steppable_optimizer.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for argument type of [`tell()`](qiskit.algorithms.optimizers.SteppableOptimizer#tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell"). + +**Parameters** + +* **eval\_fun** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Image of the function at `x_fun`. +* **eval\_jac** (*POINT |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[POINT] | None*) – Image of the gradient-jacobian at `x_jac`. + +## Attributes + + + +### eval\_fun + +`float | list[float] | None` + +`= None` + + + +### eval\_jac + +`POINT | list[POINT] | None` + +`= None` + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.UMDA.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.UMDA.md new file mode 100644 index 00000000000..73efcb24dea --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.UMDA.md @@ -0,0 +1,307 @@ +--- +title: UMDA +description: API reference for qiskit.algorithms.optimizers.UMDA +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.UMDA +--- + +# UMDA + + + +`qiskit.algorithms.optimizers.UMDA(maxiter=100, size_gen=20, alpha=0.5, callback=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/umda.py "view source code") + +Bases: [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.optimizer.Optimizer") + +Continuous Univariate Marginal Distribution Algorithm (UMDA). + +UMDA \[1] is a specific type of Estimation of Distribution Algorithm (EDA) where new individuals are sampled from univariate normal distributions and are updated in each iteration of the algorithm by the best individuals found in the previous iteration. + + + This original implementation of the UDMA optimizer for Qiskit was inspired by my (Vicente P. Soloviev) work on the EDAspy Python package \[2]. + + +EDAs are stochastic search algorithms and belong to the family of the evolutionary algorithms. The main difference is that EDAs have a probabilistic model which is updated in each iteration from the best individuals of previous generations (elite selection). Depending on the complexity of the probabilistic model, EDAs can be classified in different ways. In this case, UMDA is a univariate EDA as the embedded probabilistic model is univariate. + +UMDA has been compared to some of the already implemented algorithms in Qiskit library to optimize the parameters of variational algorithms such as QAOA or VQE and competitive results have been obtained \[1]. UMDA seems to provide very good solutions for those circuits in which the number of layers is not big. + +The optimization process can be personalized depending on the parameters chosen in the initialization. The main parameter is the population size. The bigger it is, the final result will be better. However, this increases the complexity of the algorithm and the runtime will be much heavier. In the work \[1] different experiments have been performed where population size has been set to 20 - 30. + + + The UMDA implementation has more parameters but these have default values for the initialization for better understanding of the user. For example, `lpha` parameter has been set to 0.5 and is the percentage of the population which is selected in each iteration to update the probabilistic model. + + +**Example** + +This short example runs UMDA to optimize the parameters of a variational algorithm. Here we will use the same operator as used in the algorithms introduction, which was originally computed by Qiskit Nature for an H2 molecule. The minimum energy of the H2 Hamiltonian can be found quite easily so we are able to set maxiters to a small value. + +```python +from qiskit.opflow import X, Z, I +from qiskit_aer import Aer +from qiskit.algorithms.optimizers import UMDA +from qiskit.algorithms import QAOA +from qiskit.utils import QuantumInstance + + +H2_op = (-1.052373245772859 * I ^ I) + (0.39793742484318045 * I ^ Z) + (-0.39793742484318045 * Z ^ I) + (-0.01128010425623538 * Z ^ Z) + (0.18093119978423156 * X ^ X) + +p = 2 # Toy example: 2 layers with 2 parameters in each layer: 4 variables + +opt = UMDA(maxiter=100, size_gen=20) + +backend = Aer.get_backend('statevector_simulator') +vqe = QAOA(opt, + quantum_instance=QuantumInstance(backend=backend), + reps=p) + +result = vqe.compute_minimum_eigenvalue(operator=H2_op) +``` + +If it is desired to modify the percentage of individuals considered to update the probabilistic model, then this code can be used. Here for example we set the 60% instead of the 50% predefined. + +```python +opt = UMDA(maxiter=100, size_gen=20, alpha = 0.6) + +backend = Aer.get_backend('statevector_simulator') +vqe = QAOA(opt, + quantum_instance=QuantumInstance(backend=backend), + reps=p) + +result = vqe.compute_minimum_eigenvalue(operator=qubit_op) +``` + +**References** + +\[1]: Vicente P. Soloviev, Pedro Larrañaga and Concha Bielza (2022, July). Quantum Parametric Circuit Optimization with Estimation of Distribution Algorithms. In 2022 The Genetic and Evolutionary Computation Conference (GECCO). DOI: [https://doi.org/10.1145/3520304.3533963](https://doi.org/10.1145/3520304.3533963) + +\[2]: Vicente P. Soloviev. Python package EDAspy. [https://github.com/VicentePerezSoloviev/EDAspy](https://github.com/VicentePerezSoloviev/EDAspy). + +**Parameters** + +* **maxiter** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Maximum number of iterations. +* **size\_gen** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Population size of each generation. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Percentage (0, 1] of the population to be selected as elite selection. +* **callback** (*Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, np.array,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*], None] | None*) – A callback function passed information in each iteration step. The information is, in this order: the number of function evaluations, the parameters, the best function value in this iteration. + +## Attributes + + + +### ELITE\_FACTOR + +`= 0.4` + + + +### STD\_BOUND + +`= 0.3` + + + +### alpha + +Returns the alpha parameter value (percentage of population selected to update probabilistic model) + + + +### bounds\_support\_level + +Returns bounds support level + + + +### gradient\_support\_level + +Returns gradient support level + + + +### initial\_point\_support\_level + +Returns initial point support level + + + +### is\_bounds\_ignored + +Returns is bounds ignored + + + +### is\_bounds\_required + +Returns is bounds required + + + +### is\_bounds\_supported + +Returns is bounds supported + + + +### is\_gradient\_ignored + +Returns is gradient ignored + + + +### is\_gradient\_required + +Returns is gradient required + + + +### is\_gradient\_supported + +Returns is gradient supported + + + +### is\_initial\_point\_ignored + +Returns is initial point ignored + + + +### is\_initial\_point\_required + +Returns is initial point required + + + +### is\_initial\_point\_supported + +Returns is initial point supported + + + +### maxiter + +Returns the maximum number of iterations + + + +### setting + +Return setting + + + +### settings + + + +### size\_gen + +Returns the size of the generations (number of individuals per generation) + +## Methods + +### get\_support\_level + + + +`get_support_level()` + +Get the support level dictionary. + +### gradient\_num\_diff + + + +`static gradient_num_diff(x_center, f, epsilon, max_evals_grouped=None)` + +We compute the gradient with the numeric differentiation in the parallel way, around the point x\_center. + +**Parameters** + +* **x\_center** (*ndarray*) – point around which we compute the gradient +* **f** (*func*) – the function of which the gradient is to be computed. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the epsilon used in the numeric differentiation. +* **max\_evals\_grouped** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max evals grouped, defaults to 1 (i.e. no batching). + +**Returns** + +the gradient computed + +**Return type** + +grad + +### minimize + + + +`minimize(fun, x0, jac=None, bounds=None)` + +Minimize the scalar function. + +**Parameters** + +* **fun** (*Callable\[\[POINT],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The scalar function to minimize. +* **x0** (*POINT*) – The initial point for the minimization. +* **jac** (*Callable\[\[POINT], POINT] | None*) – The gradient of the scalar function `fun`. +* **bounds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Bounds for the variables of `fun`. This argument might be ignored if the optimizer does not support bounds. + +**Returns** + +The result of the optimization, containing e.g. the result as attribute `x`. + +**Return type** + +[OptimizerResult](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") + +### print\_options + + + +`print_options()` + +Print algorithm-specific options. + +### set\_max\_evals\_grouped + + + +`set_max_evals_grouped(limit)` + +Set max evals grouped + +### set\_options + + + +`set_options(**kwargs)` + +Sets or updates values in the options dictionary. + +The options dictionary may be used internally by a given optimizer to pass additional optional values for the underlying optimizer/optimization function used. The options dictionary may be initially populated with a set of key/values when the given optimizer is constructed. + +**Parameters** + +**kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – options, given as name=value. + +### wrap\_function + + + +`static wrap_function(function, args)` + +Wrap the function to implicitly inject the args at the call of the function. + +**Parameters** + +* **function** (*func*) – the target function +* **args** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the args to be injected + +**Returns** + +wrapper + +**Return type** + +function\_wrapper + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.md new file mode 100644 index 00000000000..a0d332af743 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.md @@ -0,0 +1,97 @@ +--- +title: optimizers +description: API reference for qiskit.algorithms.optimizers +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.optimizers +--- + + + + + +# qiskit.algorithms.optimizers + + + +## Optimizers + + + +`qiskit.algorithms.optimizers` + +It contains a variety of classical optimizers for use by quantum variational algorithms, such as [`VQE`](qiskit.algorithms.VQE "qiskit.algorithms.VQE"). Logically, these optimizers can be divided into two categories: + +**[Local Optimizers](#local-optimizers)** + +Given an optimization problem, a **local optimizer** is a function that attempts to find an optimal value within the neighboring set of a candidate solution. + +**[Global Optimizers](#global-optimizers)** + +Given an optimization problem, a **global optimizer** is a function that attempts to find an optimal value among all possible solutions. + +## Optimizer Base Class + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| [`OptimizerResult`](qiskit.algorithms.optimizers.OptimizerResult "qiskit.algorithms.optimizers.OptimizerResult") | The result of an optimization routine. | +| [`OptimizerSupportLevel`](qiskit.algorithms.optimizers.OptimizerSupportLevel "qiskit.algorithms.optimizers.OptimizerSupportLevel") | Support Level enum for features such as bounds, gradient and initial point | +| [`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") | Base class for optimization algorithm. | +| [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") | Callable Protocol for minimizer. | + +## Steppable Optimizer Base Class + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | +| [`optimizer_utils`](qiskit.algorithms.optimizers.optimizer_utils#module-qiskit.algorithms.optimizers.optimizer_utils "qiskit.algorithms.optimizers.optimizer_utils") | Utils for optimizers | + +| | | +| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`SteppableOptimizer`](qiskit.algorithms.optimizers.SteppableOptimizer "qiskit.algorithms.optimizers.SteppableOptimizer") | Base class for a steppable optimizer. | +| [`AskData`](qiskit.algorithms.optimizers.AskData "qiskit.algorithms.optimizers.AskData") | Base class for return type of [`ask()`](qiskit.algorithms.optimizers.SteppableOptimizer#ask "qiskit.algorithms.optimizers.SteppableOptimizer.ask"). | +| [`TellData`](qiskit.algorithms.optimizers.TellData "qiskit.algorithms.optimizers.TellData") | Base class for argument type of [`tell()`](qiskit.algorithms.optimizers.SteppableOptimizer#tell "qiskit.algorithms.optimizers.SteppableOptimizer.tell"). | +| [`OptimizerState`](qiskit.algorithms.optimizers.OptimizerState "qiskit.algorithms.optimizers.OptimizerState") | Base class representing the state of the optimizer. | + +## Local Optimizers + +| | | +| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| [`ADAM`](qiskit.algorithms.optimizers.ADAM "qiskit.algorithms.optimizers.ADAM") | Adam and AMSGRAD optimizers. | +| [`AQGD`](qiskit.algorithms.optimizers.AQGD "qiskit.algorithms.optimizers.AQGD") | Analytic Quantum Gradient Descent (AQGD) with Epochs optimizer. | +| [`CG`](qiskit.algorithms.optimizers.CG "qiskit.algorithms.optimizers.CG") | Conjugate Gradient optimizer. | +| [`COBYLA`](qiskit.algorithms.optimizers.COBYLA "qiskit.algorithms.optimizers.COBYLA") | Constrained Optimization By Linear Approximation optimizer. | +| [`L_BFGS_B`](qiskit.algorithms.optimizers.L_BFGS_B "qiskit.algorithms.optimizers.L_BFGS_B") | Limited-memory BFGS Bound optimizer. | +| [`GSLS`](qiskit.algorithms.optimizers.GSLS "qiskit.algorithms.optimizers.GSLS") | Gaussian-smoothed Line Search. | +| [`GradientDescent`](qiskit.algorithms.optimizers.GradientDescent "qiskit.algorithms.optimizers.GradientDescent") | The gradient descent minimization routine. | +| [`GradientDescentState`](qiskit.algorithms.optimizers.GradientDescentState "qiskit.algorithms.optimizers.GradientDescentState") | State of [`GradientDescent`](qiskit.algorithms.optimizers.GradientDescent "qiskit.algorithms.optimizers.GradientDescent"). | +| [`NELDER_MEAD`](qiskit.algorithms.optimizers.NELDER_MEAD "qiskit.algorithms.optimizers.NELDER_MEAD") | Nelder-Mead optimizer. | +| [`NFT`](qiskit.algorithms.optimizers.NFT "qiskit.algorithms.optimizers.NFT") | Nakanishi-Fujii-Todo algorithm. | +| [`P_BFGS`](qiskit.algorithms.optimizers.P_BFGS "qiskit.algorithms.optimizers.P_BFGS") | Parallelized Limited-memory BFGS optimizer. | +| [`POWELL`](qiskit.algorithms.optimizers.POWELL "qiskit.algorithms.optimizers.POWELL") | Powell optimizer. | +| [`SLSQP`](qiskit.algorithms.optimizers.SLSQP "qiskit.algorithms.optimizers.SLSQP") | Sequential Least SQuares Programming optimizer. | +| [`SPSA`](qiskit.algorithms.optimizers.SPSA "qiskit.algorithms.optimizers.SPSA") | Simultaneous Perturbation Stochastic Approximation (SPSA) optimizer. | +| [`QNSPSA`](qiskit.algorithms.optimizers.QNSPSA "qiskit.algorithms.optimizers.QNSPSA") | The Quantum Natural SPSA (QN-SPSA) optimizer. | +| [`TNC`](qiskit.algorithms.optimizers.TNC "qiskit.algorithms.optimizers.TNC") | Truncated Newton (TNC) optimizer. | +| [`SciPyOptimizer`](qiskit.algorithms.optimizers.SciPyOptimizer "qiskit.algorithms.optimizers.SciPyOptimizer") | A general Qiskit Optimizer wrapping scipy.optimize.minimize. | +| [`UMDA`](qiskit.algorithms.optimizers.UMDA "qiskit.algorithms.optimizers.UMDA") | Continuous Univariate Marginal Distribution Algorithm (UMDA). | + +Qiskit also provides the following optimizers, which are built-out using the optimizers from the scikit-quant package. The scikit-quant package is not installed by default but must be explicitly installed, if desired, by the user - the optimizers therein are provided under various licenses so it has been made an optional install for the end user to choose whether to do so or not. To install the scikit-quant dependent package you can use pip install scikit-quant. + +| | | +| ---------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| [`BOBYQA`](qiskit.algorithms.optimizers.BOBYQA "qiskit.algorithms.optimizers.BOBYQA") | Bound Optimization BY Quadratic Approximation algorithm. | +| [`IMFIL`](qiskit.algorithms.optimizers.IMFIL "qiskit.algorithms.optimizers.IMFIL") | IMplicit FILtering algorithm. | +| [`SNOBFIT`](qiskit.algorithms.optimizers.SNOBFIT "qiskit.algorithms.optimizers.SNOBFIT") | Stable Noisy Optimization by Branch and FIT algorithm. | + +## Global Optimizers + +The global optimizers here all use NLopt for their core function and can only be used if their dependent NLopt package is manually installed. + +| | | +| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| [`CRS`](qiskit.algorithms.optimizers.CRS "qiskit.algorithms.optimizers.CRS") | Controlled Random Search (CRS) with local mutation optimizer. | +| [`DIRECT_L`](qiskit.algorithms.optimizers.DIRECT_L "qiskit.algorithms.optimizers.DIRECT_L") | DIviding RECTangles Locally-biased optimizer. | +| [`DIRECT_L_RAND`](qiskit.algorithms.optimizers.DIRECT_L_RAND "qiskit.algorithms.optimizers.DIRECT_L_RAND") | DIviding RECTangles Locally-biased Randomized optimizer. | +| [`ESCH`](qiskit.algorithms.optimizers.ESCH "qiskit.algorithms.optimizers.ESCH") | ESCH evolutionary optimizer. | +| [`ISRES`](qiskit.algorithms.optimizers.ISRES "qiskit.algorithms.optimizers.ISRES") | Improved Stochastic Ranking Evolution Strategy optimizer. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.LearningRate.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.LearningRate.md new file mode 100644 index 00000000000..911e13ad1b8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.LearningRate.md @@ -0,0 +1,56 @@ +--- +title: LearningRate +description: API reference for qiskit.algorithms.optimizers.optimizer_utils.LearningRate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.optimizers.optimizer_utils.LearningRate +--- + +# LearningRate + + + +`qiskit.algorithms.optimizers.optimizer_utils.LearningRate(learning_rate)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/optimizers/optimizer_utils/learning_rate.py "view source code") + +Bases: [`Generator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)") + +Represents a Learning Rate. Will be an attribute of [`GradientDescentState`](qiskit.algorithms.optimizers.GradientDescentState "qiskit.algorithms.optimizers.GradientDescentState"). Note that [`GradientDescent`](qiskit.algorithms.optimizers.GradientDescent "qiskit.algorithms.optimizers.GradientDescent") also has a learning rate. That learning rate can be a float, a list, an array, a function returning a generator and will be used to create a generator to be used during the optimization process. This class wraps `Generator` so that we can also access the last yielded value. + +**Parameters** + +**learning\_rate** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | np.ndarray | Callable\[\[], Generator\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*, None, None]]*) – Used to create a generator to iterate on. + +## Attributes + + + +### current + +Returns the current value of the learning rate. + +## Methods + +### close + + + +`close()` + +Raise GeneratorExit inside generator. + +### send + + + +`send(value)` + +Send a value into the generator. Return next yielded value or raise StopIteration. + +### throw + + + +`throw(typ, val=None, tb=None)` + +Raise an exception in the generator. Return next yielded value or raise StopIteration. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.md b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.md new file mode 100644 index 00000000000..3a8255470b0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.optimizers.optimizer_utils.md @@ -0,0 +1,28 @@ +--- +title: optimizer_utils +description: API reference for qiskit.algorithms.optimizers.optimizer_utils +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.optimizers.optimizer_utils +--- + + + + + +# qiskit.algorithms.optimizers.optimizer\_utils + +Utils for optimizers + + + +## Optimizer Utils + + + +`qiskit.algorithms.optimizers.optimizer_utils` + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | +| [`LearningRate`](qiskit.algorithms.optimizers.optimizer_utils.LearningRate "qiskit.algorithms.optimizers.optimizer_utils.LearningRate") | Represents a Learning Rate. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.BaseStateFidelity.md b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.BaseStateFidelity.md new file mode 100644 index 00000000000..a3722fff2cd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.BaseStateFidelity.md @@ -0,0 +1,71 @@ +--- +title: BaseStateFidelity +description: API reference for qiskit.algorithms.state_fidelities.BaseStateFidelity +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.state_fidelities.BaseStateFidelity +--- + +# BaseStateFidelity + + + +`qiskit.algorithms.state_fidelities.BaseStateFidelity`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/state_fidelities/base_state_fidelity.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +An interface to calculate state fidelities (state overlaps) for pairs of (parametrized) quantum circuits. The calculation depends on the particular fidelity method implementation, but can be always defined as the state overlap: + +$$ +|\langle\psi(x)|\phi(y)\rangle|^2 +$$ + +where $x$ and $y$ are optional parametrizations of the states $\psi$ and $\phi$ prepared by the circuits `circuit_1` and `circuit_2`, respectively. + +## Methods + +### create\_fidelity\_circuit + + + +`abstract create_fidelity_circuit(circuit_1, circuit_2)` + +Implementation-dependent method to create a fidelity circuit from 2 circuit inputs. + +**Parameters** + +* **circuit\_1** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – (Parametrized) quantum circuit. +* **circuit\_2** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – (Parametrized) quantum circuit. + +**Returns** + +The fidelity quantum circuit corresponding to `circuit_1` and `circuit_2`. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### run + + + +`run(circuits_1, circuits_2, values_1=None, values_2=None, **options)` + +Runs asynchronously the state overlap (fidelity) calculation between two (parametrized) circuits (first and second) for a specific set of parameter values (first and second). This calculation depends on the particular fidelity method implementation. + +**Parameters** + +* **circuits\_1** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – (Parametrized) quantum circuits preparing $|\psi\rangle$. +* **circuits\_2** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – (Parametrized) quantum circuits preparing $|\phi\rangle$. +* **values\_1** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Numerical parameters to be bound to the first set of circuits. +* **values\_2** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Numerical parameters to be bound to the second set of circuits. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > fidelity’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +**Returns** + +Primitive job for the fidelity calculation. The job’s result is an instance of `StateFidelityResult`. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.ComputeUncompute.md b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.ComputeUncompute.md new file mode 100644 index 00000000000..7c8c07acfcf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.ComputeUncompute.md @@ -0,0 +1,117 @@ +--- +title: ComputeUncompute +description: API reference for qiskit.algorithms.state_fidelities.ComputeUncompute +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.state_fidelities.ComputeUncompute +--- + +# ComputeUncompute + + + +`qiskit.algorithms.state_fidelities.ComputeUncompute(sampler, options=None, local=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/state_fidelities/compute_uncompute.py "view source code") + +Bases: [`BaseStateFidelity`](qiskit.algorithms.state_fidelities.BaseStateFidelity "qiskit.algorithms.state_fidelities.base_state_fidelity.BaseStateFidelity") + +This class leverages the sampler primitive to calculate the state fidelity of two quantum circuits following the compute-uncompute method (see \[1] for further reference). The fidelity can be defined as the state overlap. + +$$ +|\langle\psi(x)|\phi(y)\rangle|^2 +$$ + +where $x$ and $y$ are optional parametrizations of the states $\psi$ and $\phi$ prepared by the circuits `circuit_1` and `circuit_2`, respectively. + +**Reference:** \[1] Havlíček, V., Córcoles, A. D., Temme, K., Harrow, A. W., Kandala, A., Chow, J. M., & Gambetta, J. M. (2019). Supervised learning with quantum-enhanced feature spaces. Nature, 567(7747), 209-212. [arXiv:1804.11326v2 \[quant-ph\]](https://arxiv.org/pdf/1804.11326.pdf) + +**Parameters** + +* **sampler** ([*BaseSampler*](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")) – Sampler primitive instance. + +* **options** ([*Options*](qiskit.providers.Options "qiskit.providers.Options") *| None*) – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > fidelity’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +* **local** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – + + If set to `True`, the fidelity is averaged over single-qubit projectors + + $$ + \hat{O} = \frac{1}{N}\sum_{i=1}^N|0_i\rangle\langle 0_i|, + $$ + + instead of the global projector $|0\rangle\langle 0|^{\otimes n}$. This coincides with the standard (global) fidelity in the limit of the fidelity approaching 1. Might be used to increase the variance to improve trainability in algorithms such as `PVQD`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the sampler is not an instance of `BaseSampler`. + +## Attributes + + + +### options + +Return the union of estimator options setting and fidelity default options, where, if the same field is set in both, the fidelity’s default options override the primitive’s default setting. + +**Returns** + +The fidelity default + estimator options. + +## Methods + +### create\_fidelity\_circuit + + + +`create_fidelity_circuit(circuit_1, circuit_2)` + +Combines `circuit_1` and `circuit_2` to create the fidelity circuit following the compute-uncompute method. + +**Parameters** + +* **circuit\_1** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – (Parametrized) quantum circuit. +* **circuit\_2** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – (Parametrized) quantum circuit. + +**Returns** + +The fidelity quantum circuit corresponding to circuit\_1 and circuit\_2. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### run + + + +`run(circuits_1, circuits_2, values_1=None, values_2=None, **options)` + +Runs asynchronously the state overlap (fidelity) calculation between two (parametrized) circuits (first and second) for a specific set of parameter values (first and second). This calculation depends on the particular fidelity method implementation. + +**Parameters** + +* **circuits\_1** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – (Parametrized) quantum circuits preparing $|\psi\rangle$. +* **circuits\_2** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – (Parametrized) quantum circuits preparing $|\phi\rangle$. +* **values\_1** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Numerical parameters to be bound to the first set of circuits. +* **values\_2** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Numerical parameters to be bound to the second set of circuits. +* **options** – Primitive backend runtime options used for circuit execution. The order of priority is: options in `run` method > fidelity’s default options > primitive’s default setting. Higher priority setting overrides lower priority setting. + +**Returns** + +Primitive job for the fidelity calculation. The job’s result is an instance of `StateFidelityResult`. + +**Return type** + +[AlgorithmJob](qiskit.algorithms.AlgorithmJob "qiskit.algorithms.AlgorithmJob") + +### update\_default\_options + + + +`update_default_options(**options)` + +Update the fidelity’s default options setting. + +**Parameters** + +**\*\*options** – The fields to update the default options. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.StateFidelityResult.md b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.StateFidelityResult.md new file mode 100644 index 00000000000..3450e82de80 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.StateFidelityResult.md @@ -0,0 +1,52 @@ +--- +title: StateFidelityResult +description: API reference for qiskit.algorithms.state_fidelities.StateFidelityResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.state_fidelities.StateFidelityResult +--- + +# StateFidelityResult + + + +`qiskit.algorithms.state_fidelities.StateFidelityResult(fidelities, raw_fidelities, metadata, options)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/state_fidelities/state_fidelity_result.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +This class stores the result of StateFidelity computations. + +## Attributes + + + +### fidelities + +`Sequence[float]` + +List of truncated fidelity values for each pair of input circuits, ensured to be in \[0,1]. + + + +### raw\_fidelities + +`Sequence[float]` + +List of raw fidelity values for each pair of input circuits, which might not be in \[0,1] depending on the error mitigation method used. + + + +### metadata + +`Sequence[Mapping[str, Any]]` + +Additional information about the fidelity calculation. + + + +### options + +`Options` + +Primitive runtime options for the execution of the fidelity job. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.md b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.md new file mode 100644 index 00000000000..5479b77e6f4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.state_fidelities.md @@ -0,0 +1,35 @@ +--- +title: state_fidelities +description: API reference for qiskit.algorithms.state_fidelities +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.state_fidelities +--- + + + + + +# qiskit.algorithms.state\_fidelities + + + +## State Fidelity Interfaces + + + +`qiskit.algorithms.state_fidelities` + +### State Fidelities + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`BaseStateFidelity`](qiskit.algorithms.state_fidelities.BaseStateFidelity "qiskit.algorithms.state_fidelities.BaseStateFidelity")() | An interface to calculate state fidelities (state overlaps) for pairs of (parametrized) quantum circuits. | +| [`ComputeUncompute`](qiskit.algorithms.state_fidelities.ComputeUncompute "qiskit.algorithms.state_fidelities.ComputeUncompute")(sampler\[, options, local]) | This class leverages the sampler primitive to calculate the state fidelity of two quantum circuits following the compute-uncompute method (see \[1] for further reference). | + +### Results + +> | | | +> | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +> | [`StateFidelityResult`](qiskit.algorithms.state_fidelities.StateFidelityResult "qiskit.algorithms.state_fidelities.StateFidelityResult")(fidelities, ...) | This class stores the result of StateFidelity computations. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE.md new file mode 100644 index 00000000000..a30f0e6fe83 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE.md @@ -0,0 +1,109 @@ +--- +title: TrotterQRTE +description: API reference for qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE +--- + +# TrotterQRTE + + + +`qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE(product_formula=None, estimator=None, num_timesteps=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/trotterization/trotter_qrte.py "view source code") + +Bases: [`RealTimeEvolver`](qiskit.algorithms.RealTimeEvolver "qiskit.algorithms.time_evolvers.real_time_evolver.RealTimeEvolver") + +Quantum Real Time Evolution using Trotterization. Type of Trotterization is defined by a `ProductFormula` provided. + +**Examples** + +```python +from qiskit.opflow import PauliSumOp +from qiskit.quantum_info import Pauli, SparsePauliOp +from qiskit import QuantumCircuit +from qiskit.algorithms import TimeEvolutionProblem +from qiskit.algorithms.time_evolvers import TrotterQRTE +from qiskit.primitives import Estimator + +operator = PauliSumOp(SparsePauliOp([Pauli("X"), Pauli("Z")])) +initial_state = QuantumCircuit(1) +time = 1 +evolution_problem = TimeEvolutionProblem(operator, time, initial_state) +# LieTrotter with 1 rep +estimator = Estimator() +trotter_qrte = TrotterQRTE(estimator=estimator) +evolved_state = trotter_qrte.evolve(evolution_problem).evolved_state +``` + +**Parameters** + +* **product\_formula** ([*ProductFormula*](qiskit.synthesis.ProductFormula "qiskit.synthesis.ProductFormula") *| None*) – A Lie-Trotter-Suzuki product formula. If `None` provided, the Lie-Trotter first order product formula with a single repetition is used. `reps` should be 1 to obtain a number of time-steps equal to `num_timesteps` and an evaluation of [`TimeEvolutionProblem.aux_operators`](qiskit.algorithms.TimeEvolutionProblem#aux_operators "qiskit.algorithms.TimeEvolutionProblem.aux_operators") at every time-step. If `reps` is larger than 1, the true number of time-steps will be `num_timesteps * reps`. +* **num\_timesteps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of time-steps the full evolution time is devided into (repetitions of `product_formula`) +* **estimator** ([*BaseEstimator*](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") *| None*) – An estimator primitive used for calculating expectation values of `TimeEvolutionProblem.aux_operators`. + +## Attributes + + + +### estimator + +Returns an estimator. + + + +### num\_timesteps + +Returns the number of timesteps. + + + +### product\_formula + +Returns a product formula. + +## Methods + +### evolve + + + +`evolve(evolution_problem)` + +Evolves a quantum state for a given time using the Trotterization method based on a product formula provided. The result is provided in the form of a quantum circuit. If auxiliary operators are included in the `evolution_problem`, they are evaluated on the `init_state` and on the evolved state at every step (`num_timesteps` times) using an estimator primitive provided. + +**Parameters** + +**evolution\_problem** ([*TimeEvolutionProblem*](qiskit.algorithms.TimeEvolutionProblem "qiskit.algorithms.time_evolvers.time_evolution_problem.TimeEvolutionProblem")) – Instance defining evolution problem. For the included Hamiltonian, `Pauli` or `PauliSumOp` are supported by TrotterQRTE. + +**Returns** + +Evolution result that includes an evolved state as a quantum circuit and, optionally, auxiliary operators evaluated for a resulting state on an estimator primitive. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `t_param` is not set to `None` in the `TimeEvolutionProblem` (feature not currently supported). +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `aux_operators` provided in the time evolution problem but no estimator provided to the algorithm. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the `initial_state` is not provided in the `TimeEvolutionProblem`. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If an unsupported Hamiltonian type is provided. + +**Return type** + +[*TimeEvolutionResult*](qiskit.algorithms.TimeEvolutionResult "qiskit.algorithms.time_evolvers.time_evolution_result.TimeEvolutionResult") + +### supports\_aux\_operators + + + +`classmethod supports_aux_operators()` + +Whether computing the expectation value of auxiliary operators is supported. + +**Returns** + +`True` if `aux_operators` expectations in the `TimeEvolutionProblem` can be evaluated, `False` otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.md new file mode 100644 index 00000000000..6546eaa58bc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.trotterization.md @@ -0,0 +1,22 @@ +--- +title: trotterization +description: API reference for qiskit.algorithms.time_evolvers.trotterization +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.time_evolvers.trotterization +--- + + + + + +# qiskit.algorithms.time\_evolvers.trotterization + +This package contains Trotterization-based Quantum Real Time Evolution algorithm. It is compliant with the new Quantum Time Evolution Framework and makes use of `qiskit.synthesis.evolution.ProductFormula` and [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate") implementations. + +## Trotterization-based Quantum Real Time Evolution + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| [`TrotterQRTE`](qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE "qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE") | Quantum Real Time Evolution using Trotterization. | + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver.md new file mode 100644 index 00000000000..9d255fb58e7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver.md @@ -0,0 +1,42 @@ +--- +title: ForwardEulerSolver +description: API reference for qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver +--- + +# ForwardEulerSolver + + + +`qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver(function, t0, y0, t_bound, vectorized=False, support_complex=False, num_t_steps=15)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/solvers/ode/forward_euler_solver.py "view source code") + +Bases: `OdeSolver` + +Forward Euler ODE solver. + +Forward Euler ODE solver that implements an interface from SciPy. + +**Parameters** + +* **function** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)")) – Right-hand side of the system. The calling signature is `fun(t, y)`. Here `t` is a scalar, and there are two options for the ndarray `y`: It can either have shape (n,); then `fun` must return array\_like with shape (n,). Alternatively it can have shape (n, k); then `fun` must return an array\_like with shape (n, k), i.e., each column corresponds to a single column in `y`. The choice between the two options is determined by vectorized argument (see below). The vectorized implementation allows a faster approximation of the Jacobian by finite differences (required for this solver). +* **t0** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Initial time. +* **y0** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")) – Initial state. +* **t\_bound** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Boundary time - the integration won’t continue beyond it. It also determines the direction of the integration. +* **vectorized** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether `fun` is implemented in a vectorized fashion. Default is False. +* **support\_complex** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether integration in a complex domain should be supported. Generally determined by a derived solver class capabilities. Default is False. +* **num\_t\_steps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of time steps for the forward Euler method. + +## Attributes + + + +### TOO\_SMALL\_STEP + +`= 'Required step size is less than spacing between numbers.'` + + + +### step\_size + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple.md new file mode 100644 index 00000000000..f3460cb2fab --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple.md @@ -0,0 +1,56 @@ +--- +title: ImaginaryMcLachlanPrinciple +description: API reference for qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple +--- + +# ImaginaryMcLachlanPrinciple + + + +`qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple(qgt=None, gradient=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/variational_principles/imaginary_mc_lachlan_principle.py "view source code") + +Bases: [`ImaginaryVariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple "qiskit.algorithms.time_evolvers.variational.variational_principles.imaginary_variational_principle.ImaginaryVariationalPrinciple") + +Class for an Imaginary McLachlan’s Variational Principle. It aims to minimize the distance between both sides of the Wick-rotated Schrödinger equation with a quantum state given as a parametrized trial state. The principle leads to a system of linear equations handled by a linear solver. The imaginary variant means that we consider imaginary time dynamics. + +**Parameters** + +* **qgt** ([*BaseQGT*](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT") *| None*) – Instance of a the GQT class used to compute the QFI. If `None` provided, `LinCombQGT` is used. +* **gradient** ([*BaseEstimatorGradient*](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient") *| None*) – Instance of a class used to compute the state gradient. If `None` provided, `LinCombEstimatorGradient` is used. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If the gradient instance does not contain an estimator. + +## Methods + +### evolution\_gradient + + + +`evolution_gradient(hamiltonian, ansatz, param_values, gradient_params=None)` + +Calculates an evolution gradient according to the rules of this variational principle. + +**Parameters** + +* **hamiltonian** (*BaseOperator*) – Operator used for Variational Quantum Time Evolution. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Quantum state in the form of a parametrized quantum circuit. +* **param\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Values of parameters to be bound. +* **gradient\_params** (*Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None*) – List of parameters with respect to which gradients should be computed. If `None` given, gradients w\.r.t. all parameters will be computed. + +**Returns** + +An evolution gradient. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If a gradient job fails. + +**Return type** + +np.ndarray + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple.md new file mode 100644 index 00000000000..a7c8270ca0a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple.md @@ -0,0 +1,23 @@ +--- +title: ImaginaryVariationalPrinciple +description: API reference for qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple +--- + +# ImaginaryVariationalPrinciple + + + +`qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple(qgt, gradient)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/variational_principles/imaginary_variational_principle.py "view source code") + +Bases: [`VariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.VariationalPrinciple "qiskit.algorithms.time_evolvers.variational.variational_principles.variational_principle.VariationalPrinciple"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Abstract class for an Imaginary Variational Principle. The imaginary variant means that we consider imaginary time dynamics. + +**Parameters** + +* **qgt** ([*BaseQGT*](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT")) – Instance of a class used to compute the GQT. +* **gradient** ([*BaseEstimatorGradient*](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient")) – Instance of a class used to compute the state gradient. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple.md new file mode 100644 index 00000000000..0de5c9639eb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple.md @@ -0,0 +1,56 @@ +--- +title: RealMcLachlanPrinciple +description: API reference for qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple +--- + +# RealMcLachlanPrinciple + + + +`qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple(qgt=None, gradient=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/variational_principles/real_mc_lachlan_principle.py "view source code") + +Bases: [`RealVariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple "qiskit.algorithms.time_evolvers.variational.variational_principles.real_variational_principle.RealVariationalPrinciple") + +Class for a Real McLachlan’s Variational Principle. It aims to minimize the distance between both sides of the Schrödinger equation with a quantum state given as a parametrized trial state. The principle leads to a system of linear equations handled by a linear solver. The real variant means that we consider real time dynamics. + +**Parameters** + +* **qgt** ([*BaseQGT*](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT") *| None*) – Instance of a the GQT class used to compute the QFI. If `None` provided, `LinCombQGT` is used. +* **gradient** ([*BaseEstimatorGradient*](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient") *| None*) – Instance of a class used to compute the state gradient. If `None` provided, `LinCombEstimatorGradient` is used. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If the gradient instance does not contain an estimator. + +## Methods + +### evolution\_gradient + + + +`evolution_gradient(hamiltonian, ansatz, param_values, gradient_params=None)` + +Calculates an evolution gradient according to the rules of this variational principle. + +**Parameters** + +* **hamiltonian** (*BaseOperator*) – Operator used for Variational Quantum Time Evolution. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Quantum state in the form of a parametrized quantum circuit. +* **param\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Values of parameters to be bound. +* **gradient\_params** (*Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None*) – List of parameters with respect to which gradients should be computed. If `None` given, gradients w\.r.t. all parameters will be computed. + +**Returns** + +An evolution gradient. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If a gradient job fails. + +**Return type** + +np.ndarray + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple.md new file mode 100644 index 00000000000..28e79ff4d8b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple.md @@ -0,0 +1,23 @@ +--- +title: RealVariationalPrinciple +description: API reference for qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple +--- + +# RealVariationalPrinciple + + + +`qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple(qgt, gradient)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/variational_principles/real_variational_principle.py "view source code") + +Bases: [`VariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.VariationalPrinciple "qiskit.algorithms.time_evolvers.variational.variational_principles.variational_principle.VariationalPrinciple"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Class for a Real Variational Principle. The real variant means that we consider real time dynamics. + +**Parameters** + +* **qgt** ([*BaseQGT*](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT")) – Instance of a class used to compute the GQT. +* **gradient** ([*BaseEstimatorGradient*](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient")) – Instance of a class used to compute the state gradient. + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.VariationalPrinciple.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.VariationalPrinciple.md new file mode 100644 index 00000000000..72959fe10f1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.VariationalPrinciple.md @@ -0,0 +1,93 @@ +--- +title: VariationalPrinciple +description: API reference for qiskit.algorithms.time_evolvers.variational.VariationalPrinciple +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.algorithms.time_evolvers.variational.VariationalPrinciple +--- + +# VariationalPrinciple + + + +`qiskit.algorithms.time_evolvers.variational.VariationalPrinciple(qgt, gradient)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/algorithms/time_evolvers/variational/variational_principles/variational_principle.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +A Variational Principle class. It determines the time propagation of parameters in a quantum state provided as a parametrized quantum circuit (ansatz). + + + +### qgt + +Instance of a class used to compute the GQT. + +**Type** + +[BaseQGT](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT") + + + +### gradient + +Instance of a class used to compute the state gradient. + +**Type** + +[BaseEstimatorGradient](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient") + +**Parameters** + +* **qgt** ([*BaseQGT*](qiskit.algorithms.gradients.BaseQGT "qiskit.algorithms.gradients.BaseQGT")) – Instance of a class used to compute the GQT. +* **gradient** ([*BaseEstimatorGradient*](qiskit.algorithms.gradients.BaseEstimatorGradient "qiskit.algorithms.gradients.BaseEstimatorGradient")) – Instance of a class used to compute the state gradient. + +## Methods + +### evolution\_gradient + + + +`abstract evolution_gradient(hamiltonian, ansatz, param_values, gradient_params=None)` + +Calculates an evolution gradient according to the rules of this variational principle. + +**Parameters** + +* **hamiltonian** (*BaseOperator*) – Operator used for Variational Quantum Time Evolution. +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Quantum state in the form of a parametrized quantum circuit. +* **param\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Values of parameters to be bound. +* **gradient\_params** (*Sequence\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*] | None*) – List of parameters with respect to which gradients should be computed. If `None` given, gradients w\.r.t. all parameters will be computed. + +**Returns** + +An evolution gradient. + +**Return type** + +np.ndarray + +### metric\_tensor + + + +`metric_tensor(ansatz, param_values)` + +Calculates a metric tensor according to the rules of this variational principle. + +**Parameters** + +* **ansatz** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – Quantum state in the form of a parametrized quantum circuit. +* **param\_values** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Values of parameters to be bound. + +**Returns** + +Metric tensor. + +**Raises** + +[**AlgorithmError**](algorithms#qiskit.algorithms.AlgorithmError "qiskit.algorithms.AlgorithmError") – If a QFI job fails. + +**Return type** + +[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + diff --git a/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.md b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.md new file mode 100644 index 00000000000..4a573fcddb1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.algorithms.time_evolvers.variational.md @@ -0,0 +1,78 @@ +--- +title: variational +description: API reference for qiskit.algorithms.time_evolvers.variational +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.algorithms.time_evolvers.variational +--- + + + + + +# qiskit.algorithms.time\_evolvers.variational + + + +## Variational Quantum Time Evolutions + + + +`qiskit.algorithms.time_evolvers.variational` + +Algorithms for performing Variational Quantum Time Evolution of quantum states, which can be tailored to near-term devices. `VarQTE` base class exposes an interface, compliant with the Quantum Time Evolution Framework in Qiskit Terra, that is implemented by [`VarQRTE`](qiskit.algorithms.VarQRTE "qiskit.algorithms.VarQRTE") and [`VarQITE`](qiskit.algorithms.VarQITE "qiskit.algorithms.VarQITE") classes for real and imaginary time evolution respectively. The variational approach is taken according to a variational principle chosen by a user. + +**Example** + +```python +import numpy as np + +from qiskit.algorithms import TimeEvolutionProblem, VarQITE +from qiskit.algorithms.time_evolvers.variational import ImaginaryMcLachlanPrinciple +from qiskit.circuit.library import EfficientSU2 +from qiskit.quantum_info import SparsePauliOp + +observable = SparsePauliOp.from_list( + [ + ("II", 0.2252), + ("ZZ", 0.5716), + ("IZ", 0.3435), + ("ZI", -0.4347), + ("YY", 0.091), + ("XX", 0.091), + ] +) + +ansatz = EfficientSU2(observable.num_qubits, reps=1) +init_param_values = np.zeros(len(ansatz.parameters)) +for i in range(len(ansatz.parameters)): + init_param_values[i] = np.pi / 2 +var_principle = ImaginaryMcLachlanPrinciple() +time = 1 +evolution_problem = TimeEvolutionProblem(observable, time) +var_qite = VarQITE(ansatz, var_principle, init_param_values) +evolution_result = var_qite.evolve(evolution_problem) +``` + +### Variational Principles + +With variational principles we can project time evolution of a quantum state onto the parameters of a model, in our case a variational quantum circuit. + +They can be divided into two categories: Variational Quantum \_Real\_ Time Evolution, which evolves the variational ansatz under the standard Schroediger equation and Variational Quantum \_Imaginary\_ Time Evolution, which evolves under the normalized Wick-rotated Schroedinger equation. + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| [`VariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.VariationalPrinciple "qiskit.algorithms.time_evolvers.variational.VariationalPrinciple")(qgt, gradient) | A Variational Principle class. | +| [`RealVariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple "qiskit.algorithms.time_evolvers.variational.RealVariationalPrinciple")(qgt, gradient) | Class for a Real Variational Principle. | +| [`ImaginaryVariationalPrinciple`](qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple "qiskit.algorithms.time_evolvers.variational.ImaginaryVariationalPrinciple")(qgt, gradient) | Abstract class for an Imaginary Variational Principle. | +| [`RealMcLachlanPrinciple`](qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple "qiskit.algorithms.time_evolvers.variational.RealMcLachlanPrinciple")(\[qgt, gradient]) | Class for a Real McLachlan's Variational Principle. | +| [`ImaginaryMcLachlanPrinciple`](qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple "qiskit.algorithms.time_evolvers.variational.ImaginaryMcLachlanPrinciple")(\[qgt, gradient]) | Class for an Imaginary McLachlan's Variational Principle. | + +### ODE solvers + +ODE solvers that implement the SciPy ODE Solver interface. The Forward Euler Solver is a preferred choice in the presence of noise. One might also use solvers provided by SciPy directly, e.g. RK45. + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +| [`ForwardEulerSolver`](qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver "qiskit.algorithms.time_evolvers.variational.ForwardEulerSolver")(function, t0, y0, t\_bound) | Forward Euler ODE solver. | + diff --git a/docs/api/qiskit/0.46/qiskit.assembler.RunConfig.md b/docs/api/qiskit/0.46/qiskit.assembler.RunConfig.md new file mode 100644 index 00000000000..798708002db --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.assembler.RunConfig.md @@ -0,0 +1,106 @@ +--- +title: RunConfig +description: API reference for qiskit.assembler.RunConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.assembler.RunConfig +--- + +# RunConfig + + + +`qiskit.assembler.RunConfig(shots=None, seed_simulator=None, memory=None, parameter_binds=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/assembler/run_config.py "view source code") + +Bases: [`SimpleNamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace "(in Python v3.12)") + +Class for Run Configuration. + + + +### shots + +the number of shots + +**Type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### seed\_simulator + +the seed to use in the simulator + +**Type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### memory + +whether to request memory from backend (per-shot readouts) + +**Type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + + + +### parameter\_binds + +List of parameter bindings + +**Type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")] + +Initialize a RunConfig object + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of shots +* **seed\_simulator** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the seed to use in the simulator +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to request memory from backend (per-shot readouts) +* **parameter\_binds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*]*) – List of parameter bindings +* **\*\*kwargs** – optional fields + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new RunConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the RunConfig to create. It will be in the same format as output by [`to_dict()`](#qiskit.assembler.RunConfig.to_dict "qiskit.assembler.RunConfig.to_dict"). + +**Returns** + +The RunConfig from the input dictionary. + +**Return type** + +[RunConfig](#qiskit.assembler.RunConfig "qiskit.assembler.RunConfig") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the RunConfig + +**Returns** + +The dictionary form of the RunConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.AncillaQubit.md b/docs/api/qiskit/0.46/qiskit.circuit.AncillaQubit.md new file mode 100644 index 00000000000..7ccf1c31b79 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.AncillaQubit.md @@ -0,0 +1,55 @@ +--- +title: AncillaQubit +description: API reference for qiskit.circuit.AncillaQubit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.AncillaQubit +--- + +# AncillaQubit + + + +`qiskit.circuit.AncillaQubit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/quantumregister.py "view source code") + +Bases: [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") + +A qubit used as ancillary qubit. + +Creates a qubit. + +**Parameters** + +* **register** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")) – Optional. A quantum register containing the bit. +* **index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The index of the bit in its containing register. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the provided register is not a valid [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") + +## Attributes + + + +### index + +Get the index of an old-style bit in the register that owns it. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.index` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + + + +### register + +Get the register of an old-style bit. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.register` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.AncillaRegister.md b/docs/api/qiskit/0.46/qiskit.circuit.AncillaRegister.md new file mode 100644 index 00000000000..0fa6e148b76 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.AncillaRegister.md @@ -0,0 +1,90 @@ +--- +title: AncillaRegister +description: API reference for qiskit.circuit.AncillaRegister +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.AncillaRegister +--- + +# AncillaRegister + + + +`qiskit.circuit.AncillaRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/quantumregister.py "view source code") + +Bases: [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") + +Implement an ancilla register. + +Create a new generic register. + +Either the `size` or the `bits` argument must be provided. If `size` is not None, the register will be pre-populated with bits of the correct type. + +**Parameters** + +* **size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The number of bits to include in the register. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. The name of the register. If not provided, a unique name will be auto-generated from the register type. +* **bits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – Optional. A list of Bit() instances to be used to populate the register. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if both the `size` and `bits` arguments are provided, or if neither are. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `size` is not valid. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `name` is not a valid name according to the OpenQASM spec. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained duplicated bits. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained bits of an incorrect type. + +## Attributes + + + +### instances\_counter + +`= count(0)` + + + +### name + +Get the register name. + + + +### name\_format + +`= re.compile('[a-z][a-zA-Z0-9_]*')` + + + +### prefix + +`= 'a'` + + + +### size + +Get the register size. + +## Methods + +### index + + + +`index(bit)` + +Find the index of the provided bit within this register. + +### qasm + + + +`qasm()` + +Return OPENQASM string for this register. + + + The method `qiskit.circuit.quantumregister.QuantumRegister.qasm()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.AnnotatedOperation.md b/docs/api/qiskit/0.46/qiskit.circuit.AnnotatedOperation.md new file mode 100644 index 00000000000..018298ea0b8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.AnnotatedOperation.md @@ -0,0 +1,84 @@ +--- +title: AnnotatedOperation +description: API reference for qiskit.circuit.AnnotatedOperation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.AnnotatedOperation +--- + +# AnnotatedOperation + + + +`qiskit.circuit.AnnotatedOperation(base_op, modifiers)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/annotated_operation.py "view source code") + +Bases: [`Operation`](qiskit.circuit.Operation "qiskit.circuit.operation.Operation") + +Annotated operation. + +Create a new AnnotatedOperation. + +An “annotated operation” allows to add a list of modifiers to the “base” operation. For now, the only supported modifiers are of types [`InverseModifier`](qiskit.circuit.InverseModifier "qiskit.circuit.InverseModifier"), [`ControlModifier`](qiskit.circuit.ControlModifier "qiskit.circuit.ControlModifier") and [`PowerModifier`](qiskit.circuit.PowerModifier "qiskit.circuit.PowerModifier"). + +An annotated operation can be viewed as an extension of [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") (which also allows adding control to the base operation). However, an important difference is that the circuit definition of an annotated operation is not constructed when the operation is declared, and instead happens during transpilation, specifically during the [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis") transpiler pass. + +An annotated operation can be also viewed as a “higher-level” or “more abstract” object that can be added to a quantum circuit. This enables writing transpiler optimization passes that make use of this higher-level representation, for instance removing a gate that is immediately followed by its inverse. + +**Parameters** + +* **base\_op** ([*Operation*](qiskit.circuit.Operation "qiskit.circuit.operation.Operation")) – base operation being modified +* **modifiers** (*Modifier |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[Modifier]*) – ordered list of modifiers. Supported modifiers include `InverseModifier`, `ControlModifier` and `PowerModifier`. + +Examples: + +```python +op1 = AnnotatedOperation(SGate(), [InverseModifier(), ControlModifier(2)]) + +op2_inner = AnnotatedGate(SGate(), InverseModifier()) +op2 = AnnotatedGate(op2_inner, ControlModifier(2)) +``` + +Both op1 and op2 are semantically equivalent to an `SGate()` which is first inverted and then controlled by 2 qubits. + +## Attributes + + + +### name + +Unique string identifier for operation type. + + + +### num\_clbits + +Number of classical bits. + + + +### num\_qubits + +Number of qubits. + +## Methods + +### copy + + + +`copy()` + +Return a copy of the [`AnnotatedOperation`](#qiskit.circuit.AnnotatedOperation "qiskit.circuit.AnnotatedOperation"). + +**Return type** + +[*AnnotatedOperation*](#qiskit.circuit.AnnotatedOperation "qiskit.circuit.annotated_operation.AnnotatedOperation") + +### to\_matrix + + + +`to_matrix()` + +Return a matrix representation (allowing to construct Operator). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Bit.md b/docs/api/qiskit/0.46/qiskit.circuit.Bit.md new file mode 100644 index 00000000000..41f0b585135 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Bit.md @@ -0,0 +1,50 @@ +--- +title: Bit +description: API reference for qiskit.circuit.Bit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Bit +--- + +# Bit + + + +`qiskit.circuit.Bit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/bit.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Implement a generic bit. + + + This class should not be instantiated directly. This is just a superclass for [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") and [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit"). + + +Create a new generic bit. + +## Attributes + + + +### index + +Get the index of an old-style bit in the register that owns it. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.index` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + + + +### register + +Get the register of an old-style bit. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.register` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.BreakLoopOp.md b/docs/api/qiskit/0.46/qiskit.circuit.BreakLoopOp.md new file mode 100644 index 00000000000..33dab1d1251 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.BreakLoopOp.md @@ -0,0 +1,345 @@ +--- +title: BreakLoopOp +description: API reference for qiskit.circuit.BreakLoopOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.BreakLoopOp +--- + +# BreakLoopOp + + + +`qiskit.circuit.BreakLoopOp(num_qubits, num_clbits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/break_loop.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +A circuit operation which, when encountered, jumps to the end of the nearest enclosing loop. + +**Circuit symbol:** + +```python + ┌──────────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 ├ + │ break_loop │ +q_2: ┤2 ├ + │ │ +c_0: ╡0 ╞ + └──────────────┘ +``` + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.BreakLoopOp.base_class "qiskit.circuit.BreakLoopOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.CircuitInstruction.md b/docs/api/qiskit/0.46/qiskit.circuit.CircuitInstruction.md new file mode 100644 index 00000000000..e5140ee8a61 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.CircuitInstruction.md @@ -0,0 +1,82 @@ +--- +title: CircuitInstruction +description: API reference for qiskit.circuit.CircuitInstruction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.CircuitInstruction +--- + +# CircuitInstruction + + + +`qiskit.circuit.CircuitInstruction(operation, qubits=(), clbits=())`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/quantumcircuitdata.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A single instruction in a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), comprised of the [`operation`](#qiskit.circuit.CircuitInstruction.operation "qiskit.circuit.CircuitInstruction.operation") and various operands. + + + There is some possible confusion in the names of this class, [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"), and [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation"), and this class’s attribute [`operation`](#qiskit.circuit.CircuitInstruction.operation "qiskit.circuit.CircuitInstruction.operation"). Our preferred terminology is by analogy to assembly languages, where an “instruction” is made up of an “operation” and its “operands”. + + Historically, [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") came first, and originally contained the qubits it operated on and any parameters, so it was a true “instruction”. Over time, [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") became responsible for tracking qubits and clbits, and the class became better described as an “operation”. Changing the name of such a core object would be a very unpleasant API break for users, and so we have stuck with it. + + This class was created to provide a formal “instruction” context object in `QuantumCircuit.data`, which had long been made of ad-hoc tuples. With this, and the advent of the [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") interface for adding more complex objects to circuits, we took the opportunity to correct the historical naming. For the time being, this leads to an awkward case where [`CircuitInstruction.operation`](#qiskit.circuit.CircuitInstruction.operation "qiskit.circuit.CircuitInstruction.operation") is often an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instance ([`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") implements the [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") interface), but as the [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") interface gains more use, this confusion will hopefully abate. + + + + This is a lightweight internal class and there is minimal error checking; you must respect the type hints when using it. It is the user’s responsibility to ensure that direct mutations of the object do not invalidate the types, nor the restrictions placed on it by its context. Typically this will mean, for example, that [`qubits`](#qiskit.circuit.CircuitInstruction.qubits "qiskit.circuit.CircuitInstruction.qubits") must be a sequence of distinct items, with no duplicates. + + +## Attributes + + + +### operation + +`Operation` + +The logical operation that this instruction represents an execution of. + + + +### qubits + +`Tuple[Qubit, ...]` + +A sequence of the qubits that the operation is applied to. + + + +### clbits + +`Tuple[Clbit, ...]` + +A sequence of the classical bits that this operation reads from or writes to. + +## Methods + +### copy + + + +`copy()` + +Return a shallow copy of the [`CircuitInstruction`](#qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction"). + +**Return type** + +[*CircuitInstruction*](#qiskit.circuit.CircuitInstruction "qiskit.circuit.quantumcircuitdata.CircuitInstruction") + +### replace + + + +`replace(operation=None, qubits=None, clbits=None)` + +Return a new [`CircuitInstruction`](#qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") with the given fields replaced. + +**Return type** + +[*CircuitInstruction*](#qiskit.circuit.CircuitInstruction "qiskit.circuit.quantumcircuitdata.CircuitInstruction") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ClassicalRegister.md b/docs/api/qiskit/0.46/qiskit.circuit.ClassicalRegister.md new file mode 100644 index 00000000000..b0c1e06d474 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ClassicalRegister.md @@ -0,0 +1,90 @@ +--- +title: ClassicalRegister +description: API reference for qiskit.circuit.ClassicalRegister +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ClassicalRegister +--- + +# ClassicalRegister + + + +`qiskit.circuit.ClassicalRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classicalregister.py "view source code") + +Bases: [`Register`](qiskit.circuit.Register "qiskit.circuit.register.Register") + +Implement a classical register. + +Create a new generic register. + +Either the `size` or the `bits` argument must be provided. If `size` is not None, the register will be pre-populated with bits of the correct type. + +**Parameters** + +* **size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The number of bits to include in the register. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. The name of the register. If not provided, a unique name will be auto-generated from the register type. +* **bits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – Optional. A list of Bit() instances to be used to populate the register. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if both the `size` and `bits` arguments are provided, or if neither are. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `size` is not valid. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `name` is not a valid name according to the OpenQASM spec. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained duplicated bits. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained bits of an incorrect type. + +## Attributes + + + +### instances\_counter + +`= count(0)` + + + +### name + +Get the register name. + + + +### name\_format + +`= re.compile('[a-z][a-zA-Z0-9_]*')` + + + +### prefix + +`= 'c'` + + + +### size + +Get the register size. + +## Methods + +### index + + + +`index(bit)` + +Find the index of the provided bit within this register. + +### qasm + + + +`qasm()` + +Return OPENQASM string for this register. + + + The method `qiskit.circuit.classicalregister.ClassicalRegister.qasm()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Clbit.md b/docs/api/qiskit/0.46/qiskit.circuit.Clbit.md new file mode 100644 index 00000000000..ad65b20f0ba --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Clbit.md @@ -0,0 +1,55 @@ +--- +title: Clbit +description: API reference for qiskit.circuit.Clbit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Clbit +--- + +# Clbit + + + +`qiskit.circuit.Clbit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classicalregister.py "view source code") + +Bases: [`Bit`](qiskit.circuit.Bit "qiskit.circuit.bit.Bit") + +Implement a classical bit. + +Creates a classical bit. + +**Parameters** + +* **register** ([*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")) – Optional. A classical register containing the bit. +* **index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The index of the bit in its containing register. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the provided register is not a valid [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") + +## Attributes + + + +### index + +Get the index of an old-style bit in the register that owns it. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.index` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + + + +### register + +Get the register of an old-style bit. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.register` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.CommutationChecker.md b/docs/api/qiskit/0.46/qiskit.circuit.CommutationChecker.md new file mode 100644 index 00000000000..427805ee99f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.CommutationChecker.md @@ -0,0 +1,46 @@ +--- +title: CommutationChecker +description: API reference for qiskit.circuit.CommutationChecker +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.CommutationChecker +--- + +# CommutationChecker + + + +`qiskit.circuit.CommutationChecker`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/commutation_checker.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +This code is essentially copy-pasted from commutative\_analysis.py. This code cleverly hashes commutativity and non-commutativity results between DAG nodes and seems quite efficient for large Clifford circuits. They may be other possible efficiency improvements: using rule-based commutativity analysis, evicting from the cache less useful entries, etc. + +## Methods + +### commute + + + +`commute(op1, qargs1, cargs1, op2, qargs2, cargs2, max_num_qubits=3)` + +Checks if two Operations commute. The return value of True means that the operations truly commute, and the return value of False means that either the operations do not commute or that the commutation check was skipped (for example, when the operations have conditions or have too many qubits). + +**Parameters** + +* **op1** ([*Operation*](qiskit.circuit.Operation "qiskit.circuit.operation.Operation")) – first operation. +* **qargs1** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")) – first operation’s qubits. +* **cargs1** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")) – first operation’s clbits. +* **op2** ([*Operation*](qiskit.circuit.Operation "qiskit.circuit.operation.Operation")) – second operation. +* **qargs2** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")) – second operation’s qubits. +* **cargs2** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")) – second operation’s clbits. +* **max\_num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the maximum number of qubits to consider, the check may be skipped if the number of qubits for either operation exceeds this amount. + +**Returns** + +whether two operations commute. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ContinueLoopOp.md b/docs/api/qiskit/0.46/qiskit.circuit.ContinueLoopOp.md new file mode 100644 index 00000000000..460051fc9da --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ContinueLoopOp.md @@ -0,0 +1,349 @@ +--- +title: ContinueLoopOp +description: API reference for qiskit.circuit.ContinueLoopOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ContinueLoopOp +--- + +# ContinueLoopOp + + + +`qiskit.circuit.ContinueLoopOp(num_qubits, num_clbits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/continue_loop.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +A circuit operation which, when encountered, moves to the next iteration of the nearest enclosing loop. + + + Can be inserted only within the body of a loop op, and must span the full width of that block. + + +**Circuit symbol:** + +```python + ┌─────────────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 ├ + │ continue_loop │ +q_2: ┤2 ├ + │ │ +c_0: ╡0 ╞ + └─────────────────┘ +``` + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.ContinueLoopOp.base_class "qiskit.circuit.ContinueLoopOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ControlFlowOp.md b/docs/api/qiskit/0.46/qiskit.circuit.ControlFlowOp.md new file mode 100644 index 00000000000..91164e88d20 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ControlFlowOp.md @@ -0,0 +1,353 @@ +--- +title: ControlFlowOp +description: API reference for qiskit.circuit.ControlFlowOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ControlFlowOp +--- + +# ControlFlowOp + + + +`qiskit.circuit.ControlFlowOp(name, num_qubits, num_clbits, params, duration=None, unit='dt', label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/control_flow.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Abstract class to encapsulate all control flow operations. + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.ControlFlowOp.base_class "qiskit.circuit.ControlFlowOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### blocks + +Tuple of QuantumCircuits which may be executed as part of the execution of this ControlFlowOp. May be parameterized by a loop parameter to be resolved at run time. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### replace\_blocks + + + +`abstract replace_blocks(blocks)` + +Replace blocks and return new instruction. :param blocks: Tuple of QuantumCircuits to replace in instruction. + +**Returns** + +New ControlFlowOp with replaced blocks. + +**Return type** + +[*ControlFlowOp*](#qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ControlModifier.md b/docs/api/qiskit/0.46/qiskit.circuit.ControlModifier.md new file mode 100644 index 00000000000..f63c8349a84 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ControlModifier.md @@ -0,0 +1,36 @@ +--- +title: ControlModifier +description: API reference for qiskit.circuit.ControlModifier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ControlModifier +--- + +# ControlModifier + + + +`qiskit.circuit.ControlModifier(num_ctrl_qubits=0, ctrl_state=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/annotated_operation.py "view source code") + +Bases: `Modifier` + +Control modifier: specifies that the operation is controlled by `num_ctrl_qubits` and has control state `ctrl_state`. + +## Attributes + + + +### ctrl\_state + +`int | str | None` + +`= None` + + + +### num\_ctrl\_qubits + +`int` + +`= 0` + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ControlledGate.md b/docs/api/qiskit/0.46/qiskit.circuit.ControlledGate.md new file mode 100644 index 00000000000..64cc909aad8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ControlledGate.md @@ -0,0 +1,495 @@ +--- +title: ControlledGate +description: API reference for qiskit.circuit.ControlledGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ControlledGate +--- + +# ControlledGate + + + +`qiskit.circuit.ControlledGate(name, num_qubits, params, label=None, num_ctrl_qubits=1, definition=None, ctrl_state=None, base_gate=None, duration=None, unit=None, *, _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlledgate.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Controlled unitary gate. + +Create a new ControlledGate. In the new gate the first `num_ctrl_qubits` of the gate are the controls. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the gate. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits the gate acts on. +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of parameters for the gate. +* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – An optional label for the gate. +* **num\_ctrl\_qubits** (*Optional\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Number of control qubits. +* **definition** (*Optional\['QuantumCircuit']*) – A list of gate rules for implementing this gate. The elements of the list are tuples of ([`Gate()`](qiskit.circuit.Gate "qiskit.circuit.Gate"), \[qubit\_list], \[clbit\_list]). +* **ctrl\_state** (*Optional\[Union\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]]*) – The control state in decimal or as a bitstring (e.g. ‘111’). If specified as a bitstring the length must equal num\_ctrl\_qubits, MSB on left. If None, use 2\*\*num\_ctrl\_qubits-1. +* **base\_gate** (*Optional\[*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")*]*) – Gate object to be controlled. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If `num_ctrl_qubits` >= `num_qubits`. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – ctrl\_state \< 0 or ctrl\_state > 2\*\*num\_ctrl\_qubits. + +Examples: + +Create a controlled standard gate and apply it to a circuit. + +```python +from qiskit import QuantumCircuit, QuantumRegister +from qiskit.circuit.library.standard_gates import HGate + +qr = QuantumRegister(3) +qc = QuantumCircuit(qr) +c3h_gate = HGate().control(2) +qc.append(c3h_gate, qr) +qc.draw('mpl') +``` + +![../\_images/qiskit-circuit-ControlledGate-1.png](/images/api/qiskit/0.46/qiskit-circuit-ControlledGate-1.png) + +Create a controlled custom gate and apply it to a circuit. + +```python +from qiskit import QuantumCircuit, QuantumRegister +from qiskit.circuit.library.standard_gates import HGate + +qc1 = QuantumCircuit(2) +qc1.x(0) +qc1.h(1) +custom = qc1.to_gate().control(2) + +qc2 = QuantumCircuit(4) +qc2.append(custom, [0, 3, 1, 2]) +qc2.draw('mpl') +``` + +![../\_images/qiskit-circuit-ControlledGate-2.png](/images/api/qiskit/0.46/qiskit-circuit-ControlledGate-2.png) + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.ControlledGate.base_class "qiskit.circuit.ControlledGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of quantum bit arguments. +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return controlled version of gate. See [`ControlledGate`](#qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") for usage. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of controls to add to gate (default: `1`) +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – optional gate label +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The control state in decimal or as a bitstring (e.g. `'111'`). If `None`, use `2**num_ctrl_qubits-1`. + +**Returns** + +Controlled version of gate. This default algorithm uses `num_ctrl_qubits-1` ancilla qubits so returns a gate of size `num_qubits + 2*num_ctrl_qubits - 1`. + +**Return type** + +[qiskit.circuit.ControlledGate](#qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – unrecognized mode or invalid ctrl\_state + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this gate by calling inverse on the base gate. + +**Return type** + +[*ControlledGate*](#qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### power + + + +`power(exponent)` + +Creates a unitary gate as gate^exponent. + +**Parameters** + +**exponent** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Gate^exponent + +**Returns** + +To which to\_matrix is self.to\_matrix^exponent. + +**Return type** + +.library.UnitaryGate + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If Gate is not unitary + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_matrix + + + +`to_matrix()` + +Return a Numpy.array for the gate unitary matrix. + +**Returns** + +if the Gate subclass has a matrix definition. + +**Return type** + +np.ndarray + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If a Gate subclass does not implement this method an exception will be raised when this base class method is called. + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Gate parameters should be int, float, or ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Delay.md b/docs/api/qiskit/0.46/qiskit.circuit.Delay.md new file mode 100644 index 00000000000..462efb32895 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Delay.md @@ -0,0 +1,350 @@ +--- +title: Delay +description: API reference for qiskit.circuit.Delay +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Delay +--- + +# Delay + + + +`qiskit.circuit.Delay(duration, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/delay.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Do nothing and just delay/wait/idle for a specified duration. + +Create new delay instruction. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.Delay.base_class "qiskit.circuit.Delay.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration of this delay. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of quantum bit arguments. +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Special case. Return self. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_matrix + + + +`to_matrix()` + +Return a Numpy.array for the unitary matrix. This has been added to enable simulation without making delay a full Gate type. + +**Returns** + +matrix representation. + +**Return type** + +np.ndarray + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Delay parameter (i.e. duration) must be int, float or ParameterExpression. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.EquivalenceLibrary.md b/docs/api/qiskit/0.46/qiskit.circuit.EquivalenceLibrary.md new file mode 100644 index 00000000000..80500c5be3e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.EquivalenceLibrary.md @@ -0,0 +1,184 @@ +--- +title: EquivalenceLibrary +description: API reference for qiskit.circuit.EquivalenceLibrary +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.EquivalenceLibrary +--- + +# EquivalenceLibrary + + + +`qiskit.circuit.EquivalenceLibrary(*, base=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/equivalence.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A library providing a one-way mapping of Gates to their equivalent implementations as QuantumCircuits. + +Create a new equivalence library. + +**Parameters** + +**base** (*Optional\[*[*EquivalenceLibrary*](#qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")*]*) – Base equivalence library to be referenced if an entry is not found in this library. + +## Attributes + + + +### graph + +Return graph representing the equivalence library data. + +This property should be treated as read-only as it provides a reference to the internal state of the [`EquivalenceLibrary`](#qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary") object. If the graph returned by this property is mutated it could corrupt the the contents of the object. If you need to modify the output `PyDiGraph` be sure to make a copy prior to any modification. + +**Returns** + +A graph object with equivalence data in each node. + +**Return type** + +PyDiGraph + +## Methods + +### add\_equivalence + + + +`add_equivalence(gate, equivalent_circuit)` + +Add a new equivalence to the library. Future queries for the Gate will include the given circuit, in addition to all existing equivalences (including those from base). + +Parameterized Gates (those including qiskit.circuit.Parameters in their Gate.params) can be marked equivalent to parameterized circuits, provided the parameters match. + +**Parameters** + +* **gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance. +* **equivalent\_circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A circuit equivalently implementing the given Gate. + +### draw + + + +`draw(filename=None)` + +Draws the equivalence relations available in the library. + +**Parameters** + +**filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional path to write the output image to if specified this method will return None. + +**Returns** + +**Drawn equivalence library as an** + +IPython SVG if in a jupyter notebook, or as a PIL.Image otherwise. + +**Return type** + +PIL.Image or IPython.display.SVG + +**Raises** + +[**InvalidFileError**](exceptions#qiskit.exceptions.InvalidFileError "qiskit.exceptions.InvalidFileError") – if filename is not valid. + +### get\_entry + + + +`get_entry(gate)` + +Gets the set of QuantumCircuits circuits from the library which equivalently implement the given Gate. + +Parameterized circuits will have their parameters replaced with the corresponding entries from Gate.params. + +**Parameters** + +**gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance. + +**Returns** + +**A list of equivalent QuantumCircuits. If empty,** + +library contains no known decompositions of Gate. + +Returned circuits will be ordered according to their insertion in the library, from earliest to latest, from top to base. The ordering of the StandardEquivalenceLibrary will not generally be consistent across Qiskit versions. + +**Return type** + +List\[[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")] + +### has\_entry + + + +`has_entry(gate)` + +Check if a library contains any decompositions for gate. + +**Parameters** + +**gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance. + +**Returns** + +**True if gate has a known decomposition in the library.** + +False otherwise. + +**Return type** + +[Bool](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") + +### keys + + + +`keys()` + +Return list of keys to key to node index map. + +**Returns** + +Keys to the key to node index map. + +**Return type** + +List + +### node\_index + + + +`node_index(key)` + +Return node index for a given key. + +**Parameters** + +**key** (*Key*) – Key to an equivalence. + +**Returns** + +Index to the node in the graph for the given key. + +**Return type** + +Int + +### set\_entry + + + +`set_entry(gate, entry)` + +Set the equivalence record for a Gate. Future queries for the Gate will return only the circuits provided. + +Parameterized Gates (those including qiskit.circuit.Parameters in their Gate.params) can be marked equivalent to parameterized circuits, provided the parameters match. + +**Parameters** + +* **gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance. +* **entry** (*List\['QuantumCircuit']*) – A list of QuantumCircuits, each equivalently implementing the given Gate. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ForLoopOp.md b/docs/api/qiskit/0.46/qiskit.circuit.ForLoopOp.md new file mode 100644 index 00000000000..6c2f2b3120e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ForLoopOp.md @@ -0,0 +1,366 @@ +--- +title: ForLoopOp +description: API reference for qiskit.circuit.ForLoopOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ForLoopOp +--- + +# ForLoopOp + + + +`qiskit.circuit.ForLoopOp(indexset, loop_parameter, body, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/for_loop.py "view source code") + +Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") + +A circuit operation which repeatedly executes a subcircuit (`body`) parameterized by a parameter `loop_parameter` through the set of integer values provided in `indexset`. + +**Parameters** + +* **indexset** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A collection of integers to loop over. +* **loop\_parameter** ([*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter") *| None*) – The placeholder parameterizing `body` to which the values from `indexset` will be assigned. +* **body** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The loop body to be repeatedly executed. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – An optional label for identifying the instruction. + +**Circuit symbol:** + +```python + ┌───────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 ├ + │ for_loop │ +q_2: ┤2 ├ + │ │ +c_0: ╡0 ╞ + └───────────┘ +``` + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.ForLoopOp.base_class "qiskit.circuit.ForLoopOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### blocks + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### replace\_blocks + + + +`replace_blocks(blocks)` + +Replace blocks and return new instruction. :param blocks: Tuple of QuantumCircuits to replace in instruction. + +**Returns** + +New ControlFlowOp with replaced blocks. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Gate.md b/docs/api/qiskit/0.46/qiskit.circuit.Gate.md new file mode 100644 index 00000000000..910d4f5d9b0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Gate.md @@ -0,0 +1,427 @@ +--- +title: Gate +description: API reference for qiskit.circuit.Gate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Gate +--- + +# Gate + + + +`qiskit.circuit.Gate(name, num_qubits, params, label=None, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/gate.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Unitary gate. + +Create a new gate. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The Qobj name of the gate. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits the gate acts on. +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of parameters. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – An optional label for the gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.Gate.base_class "qiskit.circuit.Gate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of quantum bit arguments. +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return controlled version of gate. See [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") for usage. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of controls to add to gate (default: `1`) +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – optional gate label +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The control state in decimal or as a bitstring (e.g. `'111'`). If `None`, use `2**num_ctrl_qubits-1`. + +**Returns** + +Controlled version of gate. This default algorithm uses `num_ctrl_qubits-1` ancilla qubits so returns a gate of size `num_qubits + 2*num_ctrl_qubits - 1`. + +**Return type** + +[qiskit.circuit.ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – unrecognized mode or invalid ctrl\_state + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### power + + + +`power(exponent)` + +Creates a unitary gate as gate^exponent. + +**Parameters** + +**exponent** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Gate^exponent + +**Returns** + +To which to\_matrix is self.to\_matrix^exponent. + +**Return type** + +.library.UnitaryGate + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If Gate is not unitary + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_matrix + + + +`to_matrix()` + +Return a Numpy.array for the gate unitary matrix. + +**Returns** + +if the Gate subclass has a matrix definition. + +**Return type** + +np.ndarray + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If a Gate subclass does not implement this method an exception will be raised when this base class method is called. + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Gate parameters should be int, float, or ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.IfElseOp.md b/docs/api/qiskit/0.46/qiskit.circuit.IfElseOp.md new file mode 100644 index 00000000000..3df61193c64 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.IfElseOp.md @@ -0,0 +1,378 @@ +--- +title: IfElseOp +description: API reference for qiskit.circuit.IfElseOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.IfElseOp +--- + +# IfElseOp + + + +`qiskit.circuit.IfElseOp(condition, true_body, false_body=None, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/if_else.py "view source code") + +Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") + +A circuit operation which executes a program (`true_body`) if a provided condition (`condition`) evaluates to true, and optionally evaluates another program (`false_body`) otherwise. + +**Parameters** + +* **condition** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*expr.Expr*](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")) – A condition to be evaluated at circuit runtime which, if true, will trigger the evaluation of `true_body`. Can be specified as either a tuple of a `ClassicalRegister` to be tested for equality with a given `int`, or as a tuple of a `Clbit` to be compared to either a `bool` or an `int`. +* **true\_body** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A program to be executed if `condition` evaluates to true. +* **false\_body** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A optional program to be executed if `condition` evaluates to false. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – An optional label for identifying the instruction. + +If provided, `false_body` must be of the same `num_qubits` and `num_clbits` as `true_body`. + +The classical bits used in `condition` must be a subset of those attached to the circuit on which this `IfElseOp` will be appended. + +**Circuit symbol:** + +```python + ┌───────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 ├ + │ if_else │ +q_2: ┤2 ├ + │ │ +c_0: ╡0 ╞ + └───────────┘ +``` + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.IfElseOp.base_class "qiskit.circuit.IfElseOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### blocks + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### replace\_blocks + + + +`replace_blocks(blocks)` + +Replace blocks and return new instruction. + +**Parameters** + +**blocks** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*]*) – Iterable of circuits for “if” and “else” condition. If there is no “else” circuit it may be set to None or omitted. + +**Returns** + +New IfElseOp with replaced blocks. + +**Return type** + +[*IfElseOp*](#qiskit.circuit.IfElseOp "qiskit.circuit.controlflow.if_else.IfElseOp") + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Instruction.md b/docs/api/qiskit/0.46/qiskit.circuit.Instruction.md new file mode 100644 index 00000000000..84594a70898 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Instruction.md @@ -0,0 +1,331 @@ +--- +title: Instruction +description: API reference for qiskit.circuit.Instruction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Instruction +--- + +# Instruction + + + +`qiskit.circuit.Instruction(name, num_qubits, num_clbits, params, duration=None, unit='dt', label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/instruction.py "view source code") + +Bases: [`Operation`](qiskit.circuit.Operation "qiskit.circuit.operation.Operation") + +Generic quantum instruction. + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.Instruction.base_class "qiskit.circuit.Instruction.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](#qiskit.circuit.Instruction.name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](#qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](#qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](#qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](#qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.InstructionSet.md b/docs/api/qiskit/0.46/qiskit.circuit.InstructionSet.md new file mode 100644 index 00000000000..63441668f32 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.InstructionSet.md @@ -0,0 +1,121 @@ +--- +title: InstructionSet +description: API reference for qiskit.circuit.InstructionSet +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.InstructionSet +--- + +# InstructionSet + + + +`qiskit.circuit.InstructionSet(*, resource_requester=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/instructionset.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Instruction collection, and their contexts. + +New collection of instructions. + +The context (`qargs` and `cargs` that each instruction is attached to) is also stored separately for each instruction. + +**Parameters** + +**resource\_requester** (*Callable\[...,* [*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") *|*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*] | None*) – + +A callable that takes in the classical resource used in the condition, verifies that it is present in the attached circuit, resolves any indices into concrete [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") instances, and returns the concrete resource. If this is not given, specifying a condition with an index is forbidden, and all concrete [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") and [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") resources will be assumed to be valid. + + + The callback `resource_requester` is called once for each call to [`c_if()`](#qiskit.circuit.InstructionSet.c_if "qiskit.circuit.InstructionSet.c_if"), and assumes that a call implies that the resource will now be used. It may throw an error if the resource is not valid for usage. + + +## Attributes + + + +### cargs + +Legacy getter for the cargs components of an instruction set. This does not support mutation. + + + +### instructions + +Legacy getter for the instruction components of an instruction set. This does not support mutation. + + + +### qargs + +Legacy getter for the qargs components of an instruction set. This does not support mutation. + +## Methods + +### add + + + +`add(instruction, qargs=None, cargs=None)` + +Add an instruction and its context (where it is attached). + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on all the instructions in this set between the [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") or [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition on any of the contained instructions; it does not stack. + + +**Parameters** + +* **classical** ([*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit") *|*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the classical resource the equality condition should be on. If this is given as an integer, it will be resolved into a [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") using the same conventions as the circuit these instructions are attached to. +* **val** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the value the classical resource should be equal to. + +**Returns** + +This same instance of [`InstructionSet`](#qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet"), but now mutated to have the given equality condition. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the passed classical resource is invalid, or otherwise not resolvable to a concrete resource that these instructions are permitted to access. + +**Return type** + +[InstructionSet](#qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +**Example** + +```python +from qiskit import ClassicalRegister, QuantumRegister, QuantumCircuit + +qr = QuantumRegister(2) +cr = ClassicalRegister(2) +qc = QuantumCircuit(qr, cr) +qc.h(range(2)) +qc.measure(range(2), range(2)) + +# apply x gate if the classical register has the value 2 (10 in binary) +qc.x(0).c_if(cr, 2) + +# apply y gate if bit 0 is set to 1 +qc.y(1).c_if(0, 1) + +qc.draw('mpl') +``` + +![../\_images/qiskit-circuit-InstructionSet-1.png](/images/api/qiskit/0.46/qiskit-circuit-InstructionSet-1.png) + +### inverse + + + +`inverse()` + +Invert all instructions. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.InverseModifier.md b/docs/api/qiskit/0.46/qiskit.circuit.InverseModifier.md new file mode 100644 index 00000000000..49503610b12 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.InverseModifier.md @@ -0,0 +1,18 @@ +--- +title: InverseModifier +description: API reference for qiskit.circuit.InverseModifier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.InverseModifier +--- + +# InverseModifier + + + +`qiskit.circuit.InverseModifier`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/annotated_operation.py "view source code") + +Bases: `Modifier` + +Inverse modifier: specifies that the operation is inverted. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Operation.md b/docs/api/qiskit/0.46/qiskit.circuit.Operation.md new file mode 100644 index 00000000000..5b691c8f996 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Operation.md @@ -0,0 +1,55 @@ +--- +title: Operation +description: API reference for qiskit.circuit.Operation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Operation +--- + +# Operation + + + +`qiskit.circuit.Operation`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/operation.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Quantum Operation Interface Class. For objects that can be added to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). These objects include [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"), `Reset`, `Barrier`, `Measure`, and operators such as [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford"). The main purpose is to add an [`Operation`](#qiskit.circuit.Operation "qiskit.circuit.Operation") to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") without synthesizing it before the transpilation. + +**Example** + +Add a Clifford and a Toffoli gate to a QuantumCircuit. + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import Clifford, random_clifford + +qc = QuantumCircuit(3) +cliff = random_clifford(2) +qc.append(cliff, [0, 1]) +qc.ccx(0, 1, 2) +qc.draw('mpl') +``` + +![../\_images/qiskit-circuit-Operation-1.png](/images/api/qiskit/0.46/qiskit-circuit-Operation-1.png) + +## Attributes + + + +### name + +Unique string identifier for operation type. + + + +### num\_clbits + +Number of classical bits. + + + +### num\_qubits + +Number of qubits. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Parameter.md b/docs/api/qiskit/0.46/qiskit.circuit.Parameter.md new file mode 100644 index 00000000000..16db09dd992 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Parameter.md @@ -0,0 +1,258 @@ +--- +title: Parameter +description: API reference for qiskit.circuit.Parameter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Parameter +--- + +# Parameter + + + +`qiskit.circuit.Parameter(name, *, uuid=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/parameter.py "view source code") + +Bases: [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +Parameter Class for variable parameters. + +A parameter is a variable value that is not required to be fixed at circuit definition. + +**Examples** + +Construct a variable-rotation X gate using circuit parameters. + +```python +from qiskit.circuit import QuantumCircuit, Parameter + +# create the parameter +phi = Parameter('phi') +qc = QuantumCircuit(1) + +# parameterize the rotation +qc.rx(phi, 0) +qc.draw('mpl') + +# bind the parameters after circuit to create a bound circuit +bc = qc.assign_parameters({phi: 3.14}) +bc.measure_all() +bc.draw('mpl') +``` + +![../\_images/qiskit-circuit-Parameter-1\_00.png](/images/api/qiskit/0.46/qiskit-circuit-Parameter-1_00.png) + +![../\_images/qiskit-circuit-Parameter-1\_01.png](/images/api/qiskit/0.46/qiskit-circuit-Parameter-1_01.png) + +Create a new named [`Parameter`](#qiskit.circuit.Parameter "qiskit.circuit.Parameter"). + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the `Parameter`, used for visual representation. This can be any unicode string, e.g. “ϕ”. +* **uuid** (*UUID | None*) – For advanced usage only. Override the UUID of this parameter, in order to make it compare equal to some other parameter object. By default, two parameters with the same name do not compare equal to help catch shadowing bugs when two circuits containing the same named parameters are spurious combined. Setting the `uuid` field when creating two parameters to the same thing (along with the same name) allows them to be equal. This is useful during serialization and deserialization. + +## Attributes + + + +### name + +Returns the name of the [`Parameter`](#qiskit.circuit.Parameter "qiskit.circuit.Parameter"). + + + +### parameters + +Returns a set of the unbound Parameters in the expression. + +## Methods + +### abs + + + +`abs()` + +Absolute of a ParameterExpression + +### arccos + + + +`arccos()` + +Arccos of a ParameterExpression + +### arcsin + + + +`arcsin()` + +Arcsin of a ParameterExpression + +### arctan + + + +`arctan()` + +Arctan of a ParameterExpression + +### assign + + + +`assign(parameter, value)` + +Assign one parameter to a value, which can either be numeric or another parameter expression. + +**Parameters** + +* **parameter** ([*Parameter*](#qiskit.circuit.Parameter "qiskit.circuit.Parameter")) – A parameter in this expression whose value will be updated. +* **value** – The new value to bind to. + +**Returns** + +A new expression parameterized by any parameters which were not bound by assignment. + +### bind + + + +`bind(parameter_values, allow_unknown_parameters=False)` + +Binds the provided set of parameters to their corresponding values. + +**Parameters** + +* **parameter\_values** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Mapping of Parameter instances to the numeric value to which they will be bound. +* **allow\_unknown\_parameters** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `False`, raises an error if `parameter_values` contains Parameters in the keys outside those present in the expression. If `True`, any such parameters are simply ignored. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – + + * If parameter\_values contains Parameters outside those in self. - If a non-numeric value is passed in parameter\_values. + +* [**ZeroDivisionError**](https://docs.python.org/3/library/exceptions.html#ZeroDivisionError "(in Python v3.12)") – + + * If binding the provided values requires division by zero. + +**Returns** + +A new expression parameterized by any parameters which were not bound by parameter\_values. + +**Return type** + +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +### conjugate + + + +`conjugate()` + +Return the conjugate. + +**Return type** + +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +### cos + + + +`cos()` + +Cosine of a ParameterExpression + +### exp + + + +`exp()` + +Exponential of a ParameterExpression + +### gradient + + + +`gradient(param)` + +Get the derivative of a parameter expression w\.r.t. a specified parameter expression. + +**Parameters** + +**param** ([*Parameter*](#qiskit.circuit.Parameter "qiskit.circuit.Parameter")) – Parameter w\.r.t. which we want to take the derivative + +**Returns** + +ParameterExpression representing the gradient of param\_expr w\.r.t. param or complex or float number + +**Return type** + +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### is\_real + + + +`is_real()` + +Return whether the expression is real + +### log + + + +`log()` + +Logarithm of a ParameterExpression + +### sign + + + +`sign()` + +Sign of a ParameterExpression + +### sin + + + +`sin()` + +Sine of a ParameterExpression + +### subs + + + +`subs(parameter_map, allow_unknown_parameters=False)` + +Substitute self with the corresponding parameter in `parameter_map`. + +### sympify + + + +`sympify()` + +Return symbolic expression as a raw Sympy or Symengine object. + +Symengine is used preferentially; if both are available, the result will always be a `symengine` object. Symengine is a separate library but has integration with Sympy. + + + This is for interoperability only. Qiskit will not accept or work with raw Sympy or Symegine expressions in its parameters, because they do not contain the tracking information used in circuit-parameter binding and assignment. + + +### tan + + + +`tan()` + +Tangent of a ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ParameterExpression.md b/docs/api/qiskit/0.46/qiskit.circuit.ParameterExpression.md new file mode 100644 index 00000000000..b151f6fa9c4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ParameterExpression.md @@ -0,0 +1,250 @@ +--- +title: ParameterExpression +description: API reference for qiskit.circuit.ParameterExpression +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ParameterExpression +--- + +# ParameterExpression + + + +`qiskit.circuit.ParameterExpression(symbol_map, expr)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/parameterexpression.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +ParameterExpression class to enable creating expressions of Parameters. + +Create a new [`ParameterExpression`](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression"). + +Not intended to be called directly, but to be instantiated via operations on other [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") or [`ParameterExpression`](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") objects. + +**Parameters** + +* **symbol\_map** (*Dict\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*, \[*[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*, or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Mapping of [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instances to the `sympy.Symbol` serving as their placeholder in expr. +* **expr** (*sympy.Expr*) – Expression of `sympy.Symbol` s. + +## Attributes + + + +### parameters + +Returns a set of the unbound Parameters in the expression. + +## Methods + +### abs + + + +`abs()` + +Absolute of a ParameterExpression + +### arccos + + + +`arccos()` + +Arccos of a ParameterExpression + +### arcsin + + + +`arcsin()` + +Arcsin of a ParameterExpression + +### arctan + + + +`arctan()` + +Arctan of a ParameterExpression + +### assign + + + +`assign(parameter, value)` + +Assign one parameter to a value, which can either be numeric or another parameter expression. + +**Parameters** + +* **parameter** ([*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")) – A parameter in this expression whose value will be updated. +* **value** ([*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The new value to bind to. + +**Returns** + +A new expression parameterized by any parameters which were not bound by assignment. + +**Return type** + +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +### bind + + + +`bind(parameter_values, allow_unknown_parameters=False)` + +Binds the provided set of parameters to their corresponding values. + +**Parameters** + +* **parameter\_values** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Mapping of Parameter instances to the numeric value to which they will be bound. +* **allow\_unknown\_parameters** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `False`, raises an error if `parameter_values` contains Parameters in the keys outside those present in the expression. If `True`, any such parameters are simply ignored. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – + + * If parameter\_values contains Parameters outside those in self. - If a non-numeric value is passed in parameter\_values. + +* [**ZeroDivisionError**](https://docs.python.org/3/library/exceptions.html#ZeroDivisionError "(in Python v3.12)") – + + * If binding the provided values requires division by zero. + +**Returns** + +A new expression parameterized by any parameters which were not bound by parameter\_values. + +**Return type** + +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +### conjugate + + + +`conjugate()` + +Return the conjugate. + +**Return type** + +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +### cos + + + +`cos()` + +Cosine of a ParameterExpression + +### exp + + + +`exp()` + +Exponential of a ParameterExpression + +### gradient + + + +`gradient(param)` + +Get the derivative of a parameter expression w\.r.t. a specified parameter expression. + +**Parameters** + +**param** ([*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")) – Parameter w\.r.t. which we want to take the derivative + +**Returns** + +ParameterExpression representing the gradient of param\_expr w\.r.t. param or complex or float number + +**Return type** + +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### is\_real + + + +`is_real()` + +Return whether the expression is real + +### log + + + +`log()` + +Logarithm of a ParameterExpression + +### sign + + + +`sign()` + +Sign of a ParameterExpression + +### sin + + + +`sin()` + +Sine of a ParameterExpression + +### subs + + + +`subs(parameter_map, allow_unknown_parameters=False)` + +Returns a new Expression with replacement Parameters. + +**Parameters** + +* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Mapping from Parameters in self to the ParameterExpression instances with which they should be replaced. +* **allow\_unknown\_parameters** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `False`, raises an error if `parameter_map` contains Parameters in the keys outside those present in the expression. If `True`, any such parameters are simply ignored. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – + +* If parameter\_map contains Parameters outside those in self. - If the replacement Parameters in parameter\_map would result in a name conflict in the generated expression. + +**Returns** + +A new expression with the specified parameters replaced. + +**Return type** + +[*ParameterExpression*](#qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + +### sympify + + + +`sympify()` + +Return symbolic expression as a raw Sympy or Symengine object. + +Symengine is used preferentially; if both are available, the result will always be a `symengine` object. Symengine is a separate library but has integration with Sympy. + + + This is for interoperability only. Qiskit will not accept or work with raw Sympy or Symegine expressions in its parameters, because they do not contain the tracking information used in circuit-parameter binding and assignment. + + +### tan + + + +`tan()` + +Tangent of a ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.ParameterVector.md b/docs/api/qiskit/0.46/qiskit.circuit.ParameterVector.md new file mode 100644 index 00000000000..3ba494c36aa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.ParameterVector.md @@ -0,0 +1,52 @@ +--- +title: ParameterVector +description: API reference for qiskit.circuit.ParameterVector +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.ParameterVector +--- + +# ParameterVector + + + +`qiskit.circuit.ParameterVector(name, length=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/parametervector.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +ParameterVector class to quickly generate lists of parameters. + +## Attributes + + + +### name + +Returns the name of the ParameterVector. + + + +### params + +Returns the list of parameters in the ParameterVector. + +## Methods + +### index + + + +`index(value)` + +Returns first index of value. + +### resize + + + +`resize(length)` + +Resize the parameter vector. + +If necessary, new elements are generated. If length is smaller than before, the previous elements are cached and not re-generated if the vector is enlarged again. This is to ensure that the parameter instances do not change. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.PowerModifier.md b/docs/api/qiskit/0.46/qiskit.circuit.PowerModifier.md new file mode 100644 index 00000000000..d05c37059a4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.PowerModifier.md @@ -0,0 +1,26 @@ +--- +title: PowerModifier +description: API reference for qiskit.circuit.PowerModifier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.PowerModifier +--- + +# PowerModifier + + + +`qiskit.circuit.PowerModifier(power)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/annotated_operation.py "view source code") + +Bases: `Modifier` + +Power modifier: specifies that the operation is raised to the power `power`. + +## Attributes + + + +### power + +`float` + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.QuantumCircuit.md b/docs/api/qiskit/0.46/qiskit.circuit.QuantumCircuit.md new file mode 100644 index 00000000000..405af621f63 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.QuantumCircuit.md @@ -0,0 +1,3922 @@ +--- +title: QuantumCircuit +description: API reference for qiskit.circuit.QuantumCircuit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.QuantumCircuit +--- + +# QuantumCircuit + + + +`qiskit.circuit.QuantumCircuit(*regs, name=None, global_phase=0, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/quantumcircuit.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Create a new circuit. + +A circuit is a list of instructions bound to some registers. + +**Parameters** + +* **regs** (list([`Register`](qiskit.circuit.Register "qiskit.circuit.Register")) or list(`int`) or list(list([`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit")))) – + + The registers to be included in the circuit. + + * If a list of [`Register`](qiskit.circuit.Register "qiskit.circuit.Register") objects, represents the [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") and/or [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") objects to include in the circuit. + + For example: + + > * `QuantumCircuit(QuantumRegister(4))` + > * `QuantumCircuit(QuantumRegister(4), ClassicalRegister(3))` + > * `QuantumCircuit(QuantumRegister(4, 'qr0'), QuantumRegister(2, 'qr1'))` + + * If a list of `int`, the amount of qubits and/or classical bits to include in the circuit. It can either be a single int for just the number of quantum bits, or 2 ints for the number of quantum bits and classical bits, respectively. + + For example: + + > * `QuantumCircuit(4) # A QuantumCircuit with 4 qubits` + > * `QuantumCircuit(4, 3) # A QuantumCircuit with 4 qubits and 3 classical bits` + + * If a list of python lists containing [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") objects, a collection of [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") s to be added to the circuit. + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the name of the quantum circuit. If not set, an automatically generated string will be assigned. + +* **global\_phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *or*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")) – The global phase of the circuit in radians. + +* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Arbitrary key value metadata to associate with the circuit. This gets stored as free-form data in a dict in the [`metadata`](#qiskit.circuit.QuantumCircuit.metadata "qiskit.circuit.QuantumCircuit.metadata") attribute. It will not be directly used in the circuit. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the circuit name, if given, is not valid. + +**Examples** + +Construct a simple Bell state circuit. + +```python +from qiskit import QuantumCircuit + +qc = QuantumCircuit(2, 2) +qc.h(0) +qc.cx(0, 1) +qc.measure([0, 1], [0, 1]) +qc.draw('mpl') +``` + +![../\_images/qiskit-circuit-QuantumCircuit-1.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-1.png) + +Construct a 5-qubit GHZ circuit. + +```python +from qiskit import QuantumCircuit + +qc = QuantumCircuit(5) +qc.h(0) +qc.cx(0, range(1, 5)) +qc.measure_all() +``` + +Construct a 4-qubit Bernstein-Vazirani circuit using registers. + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit + +qr = QuantumRegister(3, 'q') +anc = QuantumRegister(1, 'ancilla') +cr = ClassicalRegister(3, 'c') +qc = QuantumCircuit(qr, anc, cr) + +qc.x(anc[0]) +qc.h(anc[0]) +qc.h(qr[0:3]) +qc.cx(qr[0:3], anc[0]) +qc.h(qr[0:3]) +qc.barrier(qr) +qc.measure(qr, cr) + +qc.draw('mpl') +``` + +![../\_images/qiskit-circuit-QuantumCircuit-2.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-2.png) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 183` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in [`QuantumCircuit.data`](#qiskit.circuit.QuantumCircuit.data "qiskit.circuit.QuantumCircuit.data"). + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### add\_bits + + + +`add_bits(bits)` + +Add Bits to the circuit. + +### add\_calibration + + + +`add_calibration(gate, qubits, schedule, params=None)` + +Register a low-level, custom pulse definition for the given gate. + +**Parameters** + +* **gate** (*Union\[*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Gate information. +* **qubits** (*Union\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, Tuple\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – List of qubits to be measured. +* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule")) – Schedule information. +* **params** (*Optional\[List\[Union\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*]]]*) – A list of parameters. + +**Raises** + +[**Exception**](https://docs.python.org/3/library/exceptions.html#Exception "(in Python v3.12)") – if the gate is of type string and params is None. + +### add\_register + + + +`add_register(*regs)` + +Add registers. + +### append + + + +`append(instruction, qargs=None, cargs=None)` + +Append one or more instructions to the end of the circuit, modifying the circuit in place. + +The `qargs` and `cargs` will be expanded and broadcast according to the rules of the given [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"), and any non-[`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") specifiers (such as integer indices) will be resolved into the relevant instances. + +If a [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") is given, it will be unwrapped, verified in the context of this circuit, and a new object will be appended to the circuit. In this case, you may not pass `qargs` or `cargs` separately. + +**Parameters** + +* **instruction** ([*Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation") *|*[*CircuitInstruction*](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")) – [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instance to append, or a [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") with all its context. +* **qargs** (*Sequence\[QubitSpecifier] | None*) – specifiers of the [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit")s to attach instruction to. +* **cargs** (*Sequence\[ClbitSpecifier] | None*) – specifiers of the [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit")s to attach instruction to. + +**Returns** + +a handle to the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s that were actually added to the circuit. + +**Return type** + +[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the operation passed is not an instance of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") . + +### assign\_parameters + +### assign\_parameters + + + +`assign_parameters(parameters: Mapping[Parameter, ParameterExpression | float] | Sequence[ParameterExpression | float], inplace: Literal[False] = False, *, flat_input: bool = False, strict: bool = True) → QuantumCircuit` + + + +`assign_parameters(parameters: Mapping[Parameter, ParameterExpression | float] | Sequence[ParameterExpression | float], inplace: Literal[True] = False, *, flat_input: bool = False, strict: bool = True) → None` + +Assign parameters to new parameters or values. + +If `parameters` is passed as a dictionary, the keys must be [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instances in the current circuit. The values of the dictionary can either be numeric values or new parameter objects. + +If `parameters` is passed as a list or array, the elements are assigned to the current parameters in the order of [`parameters`](#qiskit.circuit.QuantumCircuit.parameters "qiskit.circuit.QuantumCircuit.parameters") which is sorted alphabetically (while respecting the ordering in [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") objects). + +The values can be assigned to the current circuit object or to a copy of it. + +**Parameters** + +* **parameters** – Either a dictionary or iterable specifying the new parameter values. +* **inplace** – If False, a copy of the circuit with the bound parameters is returned. If True the circuit instance itself is modified. +* **flat\_input** – If `True` and `parameters` is a mapping type, it is assumed to be exactly a mapping of `{parameter: value}`. By default (`False`), the mapping may also contain [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") keys that point to a corresponding sequence of values, and these will be unrolled during the mapping. +* **strict** – If `False`, any parameters given in the mapping that are not used in the circuit will be ignored. If `True` (the default), an error will be raised indicating a logic error. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If parameters is a dict and contains parameters not present in the circuit. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If parameters is a list/array and the length mismatches the number of free parameters in the circuit. + +**Returns** + +A copy of the circuit with bound parameters if `inplace` is False, otherwise None. + +**Examples** + +Create a parameterized circuit and assign the parameters in-place. + +```python +from qiskit.circuit import QuantumCircuit, Parameter + +circuit = QuantumCircuit(2) +params = [Parameter('A'), Parameter('B'), Parameter('C')] +circuit.ry(params[0], 0) +circuit.crx(params[1], 0, 1) +circuit.draw('mpl') +circuit.assign_parameters({params[0]: params[2]}, inplace=True) +circuit.draw('mpl') +``` + +![../\_images/qiskit-circuit-QuantumCircuit-3\_00.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-3_00.png) + +![../\_images/qiskit-circuit-QuantumCircuit-3\_01.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-3_01.png) + +Bind the values out-of-place by list and get a copy of the original circuit. + +```python +from qiskit.circuit import QuantumCircuit, ParameterVector + +circuit = QuantumCircuit(2) +params = ParameterVector('P', 2) +circuit.ry(params[0], 0) +circuit.crx(params[1], 0, 1) + +bound_circuit = circuit.assign_parameters([1, 2]) +bound_circuit.draw('mpl') + +circuit.draw('mpl') +``` + +![../\_images/qiskit-circuit-QuantumCircuit-4\_00.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-4_00.png) + +![../\_images/qiskit-circuit-QuantumCircuit-4\_01.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-4_01.png) + +### barrier + + + +`barrier(*qargs, label=None)` + +Apply [`Barrier`](qiskit.circuit.library.Barrier "qiskit.circuit.library.Barrier"). If `qargs` is empty, applies to all qubits in the circuit. + +**Parameters** + +* **qargs** (*QubitSpecifier*) – Specification for one or more qubit arguments. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The string label of the barrier. + +**Returns** + +handle to the added instructions. + +**Return type** + +[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### bind\_parameters + + + +`bind_parameters(values)` + +Assign numeric parameters to values yielding a new circuit. + +If the values are given as list or array they are bound to the circuit in the order of [`parameters`](#qiskit.circuit.QuantumCircuit.parameters "qiskit.circuit.QuantumCircuit.parameters") (see the docstring for more details). + +To assign new Parameter objects or bind the values in-place, without yielding a new circuit, use the [`assign_parameters()`](#qiskit.circuit.QuantumCircuit.assign_parameters "qiskit.circuit.QuantumCircuit.assign_parameters") method. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.bind_parameters()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Use assign\_parameters() instead + + +**Parameters** + +**values** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – `{parameter: value, ...}` or `[value1, value2, ...]` + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If values is a dict and contains parameters not present in the circuit. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If values contains a ParameterExpression. + +**Returns** + +Copy of self with assignment substitution. + +**Return type** + +[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### break\_loop + + + +`break_loop()` + +Apply [`BreakLoopOp`](qiskit.circuit.BreakLoopOp "qiskit.circuit.BreakLoopOp"). + + + If you are using the context-manager “builder” forms of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test"), [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") or [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.while_loop"), you can only call this method if you are within a loop context, because otherwise the “resource width” of the operation cannot be determined. This would quickly lead to invalid circuits, and so if you are trying to construct a reusable loop body (without the context managers), you must also use the non-context-manager form of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") and [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.if_else"). Take care that the [`BreakLoopOp`](qiskit.circuit.BreakLoopOp "qiskit.circuit.BreakLoopOp") instruction must span all the resources of its containing loop, not just the immediate scope. + + +**Returns** + +A handle to the instruction created. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if this method was called within a builder context, but not contained within a loop. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### cast + + + +`static cast(value, type_)` + +Best effort to cast value to type. Otherwise, returns the value. + +**Return type** + +*S* | *T* + +### cbit\_argument\_conversion + + + +`cbit_argument_conversion(clbit_representation)` + +Converts several classical bit representations (such as indexes, range, etc.) into a list of classical bits. + +**Parameters** + +**clbit\_representation** (*Object*) – representation to expand + +**Returns** + +Where each tuple is a classical bit. + +**Return type** + +List([tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) + +### ccx + + + +`ccx(control_qubit1, control_qubit2, target_qubit, ctrl_state=None)` + +Apply [`CCXGate`](qiskit.circuit.library.CCXGate "qiskit.circuit.library.CCXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit1** (*QubitSpecifier*) – The qubit(s) used as the first control. +* **control\_qubit2** (*QubitSpecifier*) – The qubit(s) used as the second control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### ccz + + + +`ccz(control_qubit1, control_qubit2, target_qubit, label=None, ctrl_state=None)` + +Apply [`CCZGate`](qiskit.circuit.library.CCZGate "qiskit.circuit.library.CCZGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit1** (*QubitSpecifier*) – The qubit(s) used as the first control. +* **control\_qubit2** (*QubitSpecifier*) – The qubit(s) used as the second control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘10’). Defaults to controlling on the ‘11’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### ch + + + +`ch(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CHGate`](qiskit.circuit.library.CHGate "qiskit.circuit.library.CHGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### clear + + + +`clear()` + +Clear all instructions in self. + +Clearing the circuits will keep the metadata and calibrations. + +### cls\_instances + + + +`classmethod cls_instances()` + +Return the current number of instances of this class, useful for auto naming. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### cls\_prefix + + + +`classmethod cls_prefix()` + +Return the prefix to use for auto naming. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### cnot + + + +`cnot(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.cnot()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Use QuantumCircuit.cx as direct replacement. + + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + + + QuantumCircuit.cx: the same function with a different name. + + +### compose + + + +`compose(other, qubits=None, clbits=None, front=False, inplace=False, wrap=False)` + +Compose circuit with `other` circuit or instruction, optionally permuting wires. + +`other` can be narrower or of equal width to `self`. + +**Parameters** + +* **other** ([*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *or*[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – (sub)circuit or instruction to compose onto self. If not a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), this can be anything that [`append`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") will accept. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – qubits of self to compose onto. +* **clbits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – clbits of self to compose onto. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, front composition will be performed. This is not possible within control-flow builder context managers. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, modify the object. Otherwise return composed circuit. +* **wrap** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, wraps the other circuit into a gate (or instruction, depending on whether it contains only unitary instructions) before composing it onto self. + +**Returns** + +the composed circuit (returns None if inplace==True). + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if no correct wire mapping can be made between the two circuits, such as if `other` is wider than `self`. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if trying to emit a new circuit while `self` has a partially built control-flow context active, such as the context-manager forms of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test"), [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") and [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.while_loop"). +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if trying to compose to the front of a circuit when a control-flow builder block is active; there is no clear meaning to this action. + +**Examples** + +```python +>>> lhs.compose(rhs, qubits=[3, 2], inplace=True) +``` + +```python + ┌───┐ ┌─────┐ ┌───┐ +lqr_1_0: ───┤ H ├─── rqr_0: ──■──┤ Tdg ├ lqr_1_0: ───┤ H ├─────────────── + ├───┤ ┌─┴─┐└─────┘ ├───┤ +lqr_1_1: ───┤ X ├─── rqr_1: ┤ X ├─────── lqr_1_1: ───┤ X ├─────────────── + ┌──┴───┴──┐ └───┘ ┌──┴───┴──┐┌───┐ +lqr_1_2: ┤ U1(0.1) ├ + = lqr_1_2: ┤ U1(0.1) ├┤ X ├─────── + └─────────┘ └─────────┘└─┬─┘┌─────┐ +lqr_2_0: ─────■───── lqr_2_0: ─────■───────■──┤ Tdg ├ + ┌─┴─┐ ┌─┴─┐ └─────┘ +lqr_2_1: ───┤ X ├─── lqr_2_1: ───┤ X ├─────────────── + └───┘ └───┘ +lcr_0: 0 ═══════════ lcr_0: 0 ═══════════════════════ + +lcr_1: 0 ═══════════ lcr_1: 0 ═══════════════════════ +``` + +### continue\_loop + + + +`continue_loop()` + +Apply [`ContinueLoopOp`](qiskit.circuit.ContinueLoopOp "qiskit.circuit.ContinueLoopOp"). + + + If you are using the context-manager “builder” forms of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test"), [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") or [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.while_loop"), you can only call this method if you are within a loop context, because otherwise the “resource width” of the operation cannot be determined. This would quickly lead to invalid circuits, and so if you are trying to construct a reusable loop body (without the context managers), you must also use the non-context-manager form of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") and [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.if_else"). Take care that the [`ContinueLoopOp`](qiskit.circuit.ContinueLoopOp "qiskit.circuit.ContinueLoopOp") instruction must span all the resources of its containing loop, not just the immediate scope. + + +**Returns** + +A handle to the instruction created. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if this method was called within a builder context, but not contained within a loop. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Control this circuit on `num_ctrl_qubits` qubits. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional label to give the controlled operation for visualization. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The control state in decimal or as a bitstring (e.g. ‘111’). If None, use `2**num_ctrl_qubits - 1`. + +**Returns** + +The controlled version of this circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the circuit contains a non-unitary operation and cannot be controlled. + +### copy + + + +`copy(name=None)` + +Copy the circuit. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit. If None, then the name stays the same. + +**Returns** + +a deepcopy of the current circuit, with the specified name + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### copy\_empty\_like + + + +`copy_empty_like(name=None)` + +Return a copy of self with the same structure but empty. + +**That structure includes:** + +* name, calibrations and other metadata +* global phase +* all the qubits and clbits, including the registers + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name for the copied circuit. If None, then the name stays the same. + +**Returns** + +An empty copy of self. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### count\_ops + + + +`count_ops()` + +Count each operation kind in the circuit. + +**Returns** + +a breakdown of how many operations of each kind, sorted by amount. + +**Return type** + +OrderedDict + +### cp + + + +`cp(theta, control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CPhaseGate`](qiskit.circuit.library.CPhaseGate "qiskit.circuit.library.CPhaseGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The angle of the rotation. +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### crx + + + +`crx(theta, control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CRXGate`](qiskit.circuit.library.CRXGate "qiskit.circuit.library.CRXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The angle of the rotation. +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cry + + + +`cry(theta, control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CRYGate`](qiskit.circuit.library.CRYGate "qiskit.circuit.library.CRYGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The angle of the rotation. +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### crz + + + +`crz(theta, control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CRZGate`](qiskit.circuit.library.CRZGate "qiskit.circuit.library.CRZGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The angle of the rotation. +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cs + + + +`cs(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CSGate`](qiskit.circuit.library.CSGate "qiskit.circuit.library.CSGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### csdg + + + +`csdg(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CSdgGate`](qiskit.circuit.library.CSdgGate "qiskit.circuit.library.CSdgGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cswap + + + +`cswap(control_qubit, target_qubit1, target_qubit2, label=None, ctrl_state=None)` + +Apply [`CSwapGate`](qiskit.circuit.library.CSwapGate "qiskit.circuit.library.CSwapGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit1** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **target\_qubit2** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. `'1'`). Defaults to controlling on the `'1'` state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### csx + + + +`csx(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CSXGate`](qiskit.circuit.library.CSXGate "qiskit.circuit.library.CSXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cu + + + +`cu(theta, phi, lam, gamma, control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CUGate`](qiskit.circuit.library.CUGate "qiskit.circuit.library.CUGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The $\theta$ rotation angle of the gate. +* **phi** (*ParameterValueType*) – The $\phi$ rotation angle of the gate. +* **lam** (*ParameterValueType*) – The $\lambda$ rotation angle of the gate. +* **gamma** (*ParameterValueType*) – The global phase applied of the U gate, if applied. +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cx + + + +`cx(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the control. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cy + + + +`cy(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CYGate`](qiskit.circuit.library.CYGate "qiskit.circuit.library.CYGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the controls. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### cz + + + +`cz(control_qubit, target_qubit, label=None, ctrl_state=None)` + +Apply [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit** (*QubitSpecifier*) – The qubit(s) used as the controls. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. +* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### dcx + + + +`dcx(qubit1, qubit2)` + +Apply [`DCXGate`](qiskit.circuit.library.DCXGate "qiskit.circuit.library.DCXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### decompose + + + +`decompose(gates_to_decompose=None, reps=1)` + +Call a decomposition pass on this circuit, to decompose one level (shallow decompose). + +**Parameters** + +* **gates\_to\_decompose** ([*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*)*) – Optional subset of gates to decompose. Can be a gate type, such as `HGate`, or a gate name, such as ‘h’, or a gate label, such as ‘My H Gate’, or a list of any combination of these. If a gate name is entered, it will decompose all gates with that name, whether the gates have labels or not. Defaults to all gates in circuit. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional number of times the circuit should be decomposed. For instance, `reps=2` equals calling `circuit.decompose().decompose()`. can decompose specific gates specific time + +**Returns** + +a circuit one level decomposed + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### delay + + + +`delay(duration, qarg=None, unit='dt')` + +Apply [`Delay`](qiskit.circuit.Delay "qiskit.circuit.Delay"). If qarg is `None`, applies to all qubits. When applying to multiple qubits, delays with the same duration will be created. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *or*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")) – duration of the delay. +* **qarg** (*Object*) – qubit argument to apply this delay. +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – unit of the duration. Supported units: `'s'`, `'ms'`, `'us'`, `'ns'`, `'ps'`, and `'dt'`. Default is `'dt'`, i.e. integer time unit depending on the target backend. + +**Returns** + +handle to the added instructions. + +**Return type** + +[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if arguments have bad format. + +### depth + + + +`depth(filter_function=>)` + +Return circuit depth (i.e., length of critical path). + +**Parameters** + +**filter\_function** (*callable*) – A function to filter instructions. Should take as input a tuple of (Instruction, list(Qubit), list(Clbit)). Instructions for which the function returns False are ignored in the computation of the circuit depth. By default filters out “directives”, such as barrier or snapshot. + +**Returns** + +Depth of circuit. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +**Notes** + +The circuit depth and the DAG depth need not be the same. + +### diagonal + + + +`diagonal(diag, qubit)` + +Attach a diagonal gate to a circuit. + +The decomposition is based on Theorem 7 given in “Synthesis of Quantum Logic Circuits” by Shende et al. ([https://arxiv.org/pdf/quant-ph/0406176.pdf](https://arxiv.org/pdf/quant-ph/0406176.pdf)). + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.diagonal()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, compose the circuit with a qiskit.circuit.library.Diagonal circuit. + + +**Parameters** + +* **diag** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – list of the 2^k diagonal entries (for a diagonal gate on k qubits). Must contain at least two entries +* **qubit** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – list of k qubits the diagonal is acting on (the order of the qubits specifies the computational basis in which the diagonal gate is provided: the first element in diag acts on the state where all the qubits in q are in the state 0, the second entry acts on the state where all the qubits q\[1],…,q\[k-1] are in the state zero and q\[0] is in the state 1, and so on) + +**Returns** + +the diagonal gate which was attached to the circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the list of the diagonal entries or the qubit list is in bad format; if the number of diagonal entries is not 2^k, where k denotes the number of qubits + +### draw + + + +`draw(output=None, scale=None, filename=None, style=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=True, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30)` + +Draw the quantum circuit. Use the output parameter to choose the drawing format: + +**text**: ASCII art TextDrawing that can be printed in the console. + +**mpl**: images with color rendered purely in Python using matplotlib. + +**latex**: high-quality images compiled via latex. + +**latex\_source**: raw uncompiled latex output. + + + Support for [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") nodes in conditions and `SwitchCaseOp.target` fields is preliminary and incomplete. The `text` and `mpl` drawers will make a best-effort attempt to show data dependencies, but the LaTeX-based drawers will skip these completely. + + +**Parameters** + +* **output** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – select the output method to use for drawing the circuit. Valid choices are `text`, `mpl`, `latex`, `latex_source`. By default the text drawer is used unless the user config file (usually `~/.qiskit/settings.conf`) has an alternative backend set as the default. For example, `circuit_drawer = latex`. If the output kwarg is set, that backend will always be used over the default in the user config file. +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – scale of image to draw (shrink if \< 1.0). Only used by the mpl, latex and latex\_source outputs. Defaults to 1.0. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. Defaults to None. +* **style** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – dictionary of style or file name of style json file. This option is only used by the mpl or latex output type. If style is a str, it is used as the path to a json file which contains a style dict. The file will be opened, parsed, and then any style elements in the dict will replace the default values in the input dict. A file to be loaded must end in `.json`, but the name entered here can omit `.json`. For example, `style='iqp.json'` or `style='iqp'`. If style is a dict and the `'name'` key is set, that name will be used to load a json file, followed by loading the other items in the style dict. For example, `style={'name': 'iqp'}`. If style is not a str and name is not a key in the style dict, then the default value from the user config file (usually `~/.qiskit/settings.conf`) will be used, for example, `circuit_mpl_style = iqp`. If none of these are set, the clifford style will be used. The search path for style json files can be specified in the user config, for example, `circuit_mpl_style_path = /home/user/styles:/home/user`. See: [`DefaultStyle`](qiskit.visualization.circuit.qcstyle.DefaultStyle "qiskit.visualization.circuit.qcstyle.DefaultStyle") for more information on the contents. +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – when set to true, show the circuit in a new window (for mpl this depends on the matplotlib backend being used supporting this). Note when used with either the text or the latex\_source output type this has no effect and will be silently ignored. Defaults to False. +* **reverse\_bits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – when set to True, reverse the bit order inside registers for the output visualization. Defaults to False unless the user config file (usually `~/.qiskit/settings.conf`) has an alternative value set. For example, `circuit_reverse_bits = True`. +* **plot\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – enable/disable drawing barriers in the output circuit. Defaults to True. +* **justify** (*string*) – options are `left`, `right` or `none`. If anything else is supplied, it defaults to left justified. It refers to where gates should be placed in the output circuit if there is an option. `none` results in each gate being placed in its own column. +* **vertical\_compression** (*string*) – `high`, `medium` or `low`. It merges the lines generated by the text output so the drawing will take less vertical room. Default is `medium`. Only used by the text output, will be silently ignored otherwise. +* **idle\_wires** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – include idle wires (wires with no circuit elements) in output visualization. Default is True. +* **with\_layout** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – include layout information, with labels on the physical layout. Default is True. +* **fold** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – sets pagination. It can be disabled using -1. In text, sets the length of the lines. This is useful when the drawing does not fit in the console. If None (default), it will try to guess the console width using `shutil.get_terminal_size()`. However, if running in jupyter, the default line length is set to 80 characters. In mpl, it is the number of (visual) layers before folding. Default is 25. +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – Only used by the mpl backend. An optional Axes object to be used for the visualization output. If none is specified, a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. +* **initial\_state** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional. Adds `|0>` in the beginning of the wire. Default is False. +* **cregbundle** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional. If set True, bundle classical registers. Default is True, except for when `output` is set to `"text"`. +* **wire\_order** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Optional. A list of integers used to reorder the display of the bits. The list must have an entry for every bit with the bits in the range 0 to (`num_qubits` + `num_clbits`). +* **expr\_len** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The number of characters to display if an [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") is used for the condition in a [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp"). If this number is exceeded, the string will be truncated at that number and ‘…’ added to the end. + +**Returns** + +`TextDrawing` or `matplotlib.figure` or `PIL.Image` or [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"): + +* **TextDrawing (output=’text’)** + + A drawing that can be printed as ascii art. + +* **matplotlib.figure.Figure (output=’mpl’)** + + A matplotlib figure object for the circuit diagram. + +* **PIL.Image (output=’latex’)** + + An in-memory representation of the image of the circuit diagram. + +* **str (output=’latex\_source’)** + + The LaTeX source code for visualizing the circuit diagram. + +**Raises** + +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – when an invalid output method is selected +* [**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.12)") – when the output methods requires non-installed libraries. + +**Example** + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit +q = QuantumRegister(1) +c = ClassicalRegister(1) +qc = QuantumCircuit(q, c) +qc.h(q) +qc.measure(q, c) +qc.draw(output='mpl', style={'backgroundcolor': '#EEEEEE'}) +``` + +![../\_images/qiskit-circuit-QuantumCircuit-5.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-5.png) + +### ecr + + + +`ecr(qubit1, qubit2)` + +Apply [`ECRGate`](qiskit.circuit.library.ECRGate "qiskit.circuit.library.ECRGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### find\_bit + + + +`find_bit(bit)` + +Find locations in the circuit which can be used to reference a given [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit"). + +**Parameters** + +**bit** ([*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")) – The bit to locate. + +**Returns** + +**A 2-tuple. The first element (`index`)** + +contains the index at which the `Bit` can be found (in either [`qubits`](#qiskit.circuit.QuantumCircuit.qubits "qiskit.circuit.QuantumCircuit.qubits"), [`clbits`](#qiskit.circuit.QuantumCircuit.clbits "qiskit.circuit.QuantumCircuit.clbits"), depending on its type). The second element (`registers`) is a list of `(register, index)` pairs with an entry for each [`Register`](qiskit.circuit.Register "qiskit.circuit.Register") in the circuit which contains the [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") (and the index in the [`Register`](qiskit.circuit.Register "qiskit.circuit.Register") at which it can be found). + +**Return type** + +namedtuple([int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), List\[Tuple([Register](qiskit.circuit.Register "qiskit.circuit.Register"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"))]) + +**Notes** + +The circuit index of an [`AncillaQubit`](qiskit.circuit.AncillaQubit "qiskit.circuit.AncillaQubit") will be its index in [`qubits`](#qiskit.circuit.QuantumCircuit.qubits "qiskit.circuit.QuantumCircuit.qubits"), not [`ancillas`](#qiskit.circuit.QuantumCircuit.ancillas "qiskit.circuit.QuantumCircuit.ancillas"). + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the supplied [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") was of an unknown type. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the supplied [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") could not be found on the circuit. + +**Return type** + +*BitLocations* + +### for\_loop + +### for\_loop + + + +`for_loop(indexset: Iterable[int], loop_parameter: Parameter | None, body: None, qubits: None, clbits: None, *, label: str | None) → qiskit.circuit.controlflow.for_loop.ForLoopContext` + + + +`for_loop(indexset: Iterable[int], loop_parameter: Parameter | None, body: QuantumCircuit, qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None) → InstructionSet` + +Create a `for` loop on this circuit. + +There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a [`ForLoopOp`](qiskit.circuit.ForLoopOp "qiskit.circuit.ForLoopOp") with the given `body`. If `body` (and `qubits` and `clbits`) are *not* passed, then this acts as a context manager, which, when entered, provides a loop variable (unless one is given, in which case it will be reused) and will automatically build a [`ForLoopOp`](qiskit.circuit.ForLoopOp "qiskit.circuit.ForLoopOp") when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you. + +For example: + +```python +from qiskit import QuantumCircuit +qc = QuantumCircuit(2, 1) + +with qc.for_loop(range(5)) as i: + qc.h(0) + qc.cx(0, 1) + qc.measure(0, 0) + qc.break_loop().c_if(0, True) +``` + +**Parameters** + +* **indexset** (*Iterable\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A collection of integers to loop over. Always necessary. + +* **loop\_parameter** (*Optional\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*]*) – + + The parameter used within `body` to which the values from `indexset` will be assigned. In the context-manager form, if this argument is not supplied, then a loop parameter will be allocated for you and returned as the value of the `with` statement. This will only be bound into the circuit if it is used within the body. + + If this argument is `None` in the manual form of this method, `body` will be repeated once for each of the items in `indexset` but their values will be ignored. + +* **body** (*Optional\[*[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The loop body to be repeatedly executed. Omit this to use the context-manager mode. + +* **qubits** (*Optional\[Sequence\[QubitSpecifier]]*) – The circuit qubits over which the loop body should be run. Omit this to use the context-manager mode. + +* **clbits** (*Optional\[Sequence\[ClbitSpecifier]]*) – The circuit clbits over which the loop body should be run. Omit this to use the context-manager mode. + +* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – The string label of the instruction in the circuit. + +**Returns** + +depending on the call signature, either a context manager for creating the for loop (it will automatically be added to the circuit at the end of the block), or an [`InstructionSet`](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") handle to the appended loop operation. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or ForLoopContext + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used. + +### fredkin + + + +`fredkin(control_qubit, target_qubit1, target_qubit2)` + +Apply [`CSwapGate`](qiskit.circuit.library.CSwapGate "qiskit.circuit.library.CSwapGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.fredkin()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Use QuantumCircuit.cswap as direct replacement. + + +**Parameters** + +* **control\_qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the control. +* **target\_qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) targeted by the gate. +* **target\_qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) targeted by the gate. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + + + QuantumCircuit.cswap: the same function with a different name. + + +### from\_instructions + + + +`static from_instructions(instructions, *, qubits=(), clbits=(), name=None, global_phase=0, metadata=None)` + +Construct a circuit from an iterable of CircuitInstructions. + +**Parameters** + +* **instructions** (*Iterable\[*[*CircuitInstruction*](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") *|*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*, Iterable\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*, Iterable\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*], Iterable\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]]]*) – The instructions to add to the circuit. +* **qubits** (*Iterable\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – Any qubits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of qubits. +* **clbits** (*Iterable\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – Any classical bits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of classical bits. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The name of the circuit. +* **global\_phase** (*ParameterValueType*) – The global phase of the circuit in radians. +* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Arbitrary key value metadata to associate with the circuit. + +**Returns** + +The quantum circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### from\_qasm\_file + + + +`static from_qasm_file(path)` + +Read an OpenQASM 2.0 program from a file and convert to an instance of [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +**path** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Path to the file for an OpenQASM 2 program + +**Returns** + +The QuantumCircuit object for the input OpenQASM 2. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + + + [`qasm2.load()`](qasm2#qiskit.qasm2.load "qiskit.qasm2.load"): the complete interface to the OpenQASM 2 importer. + + +### from\_qasm\_str + + + +`static from_qasm_str(qasm_str)` + +Convert a string containing an OpenQASM 2.0 program to a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +**qasm\_str** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A string containing an OpenQASM 2.0 program. + +**Returns** + +The QuantumCircuit object for the input OpenQASM 2 + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + + + [`qasm2.loads()`](qasm2#qiskit.qasm2.loads "qiskit.qasm2.loads"): the complete interface to the OpenQASM 2 importer. + + +### get\_instructions + + + +`get_instructions(name)` + +Get instructions matching name. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of instruction to. + +**Returns** + +list of (instruction, qargs, cargs). + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")([tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) + +### h + + + +`h(qubit)` + +Apply [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### hamiltonian + + + +`hamiltonian(operator, time, qubits, label=None)` + +Apply hamiltonian evolution to qubits. + +This gate resolves to a [`UnitaryGate`](qiskit.circuit.library.UnitaryGate "qiskit.circuit.library.UnitaryGate") as $U(t) = exp(-i t H)$, which can be decomposed into basis gates if it is 2 qubits or less, or simulated directly in Aer for more qubits. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.hamiltonian()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.HamiltonianGate to the circuit. + + +**Parameters** + +* **operator** (*matrix or* [*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – a hermitian operator. +* **time** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *or*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")) – time evolution parameter. +* **qubits** (*Union\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, Tuple\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – The circuit qubits to apply the transformation to. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – unitary name for backend \[Default: None]. + +**Returns** + +The quantum circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### has\_calibration\_for + + + +`has_calibration_for(instruction)` + +Return True if the circuit has a calibration defined for the instruction context. In this case, the operation does not need to be translated to the device basis. + +### has\_register + + + +`has_register(register)` + +Test if this circuit has the register r. + +**Parameters** + +**register** ([*Register*](qiskit.circuit.Register "qiskit.circuit.Register")) – a quantum or classical register. + +**Returns** + +True if the register is contained in this circuit. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### i + + + +`i(qubit)` + +Apply [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.i()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Use QuantumCircuit.id as direct replacement. + + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### id + + + +`id(qubit)` + +Apply [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### if\_else + + + +`if_else(condition, true_body, false_body, qubits, clbits, label=None)` + +Apply [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp"). + + + This method does not have an associated context-manager form, because it is already handled by the [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") method. You can use the `else` part of that with something such as: + + ```python + from qiskit.circuit import QuantumCircuit, Qubit, Clbit + bits = [Qubit(), Qubit(), Clbit()] + qc = QuantumCircuit(bits) + qc.h(0) + qc.cx(0, 1) + qc.measure(0, 0) + with qc.if_test((bits[2], 0)) as else_: + qc.h(0) + with else_: + qc.x(0) + ``` + + +**Parameters** + +* **condition** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*,* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*]*) – A condition to be evaluated at circuit runtime which, if true, will trigger the evaluation of `true_body`. Can be specified as either a tuple of a `ClassicalRegister` to be tested for equality with a given `int`, or as a tuple of a `Clbit` to be compared to either a `bool` or an `int`. +* **true\_body** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The circuit body to be run if `condition` is true. +* **false\_body** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The circuit to be run if `condition` is false. +* **qubits** (*Sequence\[QubitSpecifier]*) – The circuit qubits over which the if/else should be run. +* **clbits** (*Sequence\[ClbitSpecifier]*) – The circuit clbits over which the if/else should be run. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the instruction in the circuit. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the provided condition references Clbits outside the enclosing circuit. + +**Returns** + +A handle to the instruction created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### if\_test + +### if\_test + + + +`if_test(condition: tuple[ClassicalRegister | Clbit, int], true_body: None, qubits: None, clbits: None, *, label: str | None) → qiskit.circuit.controlflow.if_else.IfContext` + + + +`if_test(condition: tuple[ClassicalRegister | Clbit, int], true_body: QuantumCircuit, qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None = None) → InstructionSet` + +Create an `if` statement on this circuit. + +There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp") with the given `true_body`, and there will be no branch for the `false` condition (see also the [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.if_else") method). However, if `true_body` (and `qubits` and `clbits`) are *not* passed, then this acts as a context manager, which can be used to build `if` statements. The return value of the `with` statement is a chainable context manager, which can be used to create subsequent `else` blocks. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you. + +For example: + +```python +from qiskit.circuit import QuantumCircuit, Qubit, Clbit +bits = [Qubit(), Qubit(), Qubit(), Clbit(), Clbit()] +qc = QuantumCircuit(bits) + +qc.h(0) +qc.cx(0, 1) +qc.measure(0, 0) +qc.h(0) +qc.cx(0, 1) +qc.measure(0, 1) + +with qc.if_test((bits[3], 0)) as else_: + qc.x(2) +with else_: + qc.h(2) + qc.z(2) +``` + +**Parameters** + +* **condition** (*Tuple\[Union\[*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A condition to be evaluated at circuit runtime which, if true, will trigger the evaluation of `true_body`. Can be specified as either a tuple of a `ClassicalRegister` to be tested for equality with a given `int`, or as a tuple of a `Clbit` to be compared to either a `bool` or an `int`. +* **true\_body** (*Optional\[*[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The circuit body to be run if `condition` is true. +* **qubits** (*Optional\[Sequence\[QubitSpecifier]]*) – The circuit qubits over which the if/else should be run. +* **clbits** (*Optional\[Sequence\[ClbitSpecifier]]*) – The circuit clbits over which the if/else should be run. +* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – The string label of the instruction in the circuit. + +**Returns** + +depending on the call signature, either a context manager for creating the `if` block (it will automatically be added to the circuit at the end of the block), or an [`InstructionSet`](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") handle to the appended conditional operation. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or IfContext + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the provided condition references Clbits outside the enclosing circuit. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used. + +**Returns** + +A handle to the instruction created. + +### initialize + + + +`initialize(params, qubits=None, normalize=False)` + +Initialize qubits in a specific state. + +Qubit initialization is done by first resetting the qubits to $|0\rangle$ followed by calling [`StatePreparation`](qiskit.circuit.library.StatePreparation "qiskit.circuit.library.StatePreparation") class to prepare the qubits in a specified state. Both these steps are included in the [`Initialize`](qiskit.circuit.library.Initialize "qiskit.circuit.library.Initialize") instruction. + +**Parameters** + +* **params** (*Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – + + The state to initialize to, can be either of the following. + + * Statevector or vector of complex amplitudes to initialize to. + * Labels of basis states of the Pauli eigenstates Z, X, Y. See [`Statevector.from_label()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label"). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to $|1\rangle$ and the qubit one to $|0\rangle$. + * An integer that is used as a bitmap indicating which qubits to initialize to $|1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $|1\rangle$ and qubit 1 to $|0\rangle$. + +* **qubits** (*Sequence\[QubitSpecifier] | None*) – Qubits to initialize. If `None` the initialization is applied to all qubits in the circuit. + +* **normalize** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to normalize an input array to a unit vector. + +**Returns** + +A handle to the instructions created. + +**Examples** + +Prepare a qubit in the state $(|0\rangle - |1\rangle) / \sqrt{2}$. + +```python +import numpy as np +from qiskit import QuantumCircuit + +circuit = QuantumCircuit(1) +circuit.initialize([1/np.sqrt(2), -1/np.sqrt(2)], 0) +circuit.draw() +``` + +output: + +```python + ┌──────────────────────────────┐ +q_0: ┤ Initialize(0.70711,-0.70711) ├ + └──────────────────────────────┘ +``` + +Initialize from a string two qubits in the state $|10\rangle$. The order of the labels is reversed with respect to qubit index. More information about labels for basis states are in [`Statevector.from_label()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label"). + +```python +import numpy as np +from qiskit import QuantumCircuit + +circuit = QuantumCircuit(2) +circuit.initialize('01', circuit.qubits) +circuit.draw() +``` + +output: + +```python + ┌──────────────────┐ +q_0: ┤0 ├ + │ Initialize(0,1) │ +q_1: ┤1 ├ + └──────────────────┘ +``` + +Initialize two qubits from an array of complex amplitudes. + +```python +import numpy as np +from qiskit import QuantumCircuit + +circuit = QuantumCircuit(2) +circuit.initialize([0, 1/np.sqrt(2), -1.j/np.sqrt(2), 0], circuit.qubits) +circuit.draw() +``` + +output: + +```python + ┌────────────────────────────────────┐ +q_0: ┤0 ├ + │ Initialize(0,0.70711,-0.70711j,0) │ +q_1: ┤1 ├ + └────────────────────────────────────┘ +``` + +### inverse + + + +`inverse()` + +Invert (take adjoint of) this circuit. + +This is done by recursively inverting all gates. + +**Returns** + +the inverted circuit + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the circuit cannot be inverted. + +**Examples** + +input: + +```python + ┌───┐ +q_0: ┤ H ├─────■────── + └───┘┌────┴─────┐ +q_1: ─────┤ RX(1.57) ├ + └──────────┘ +``` + +output: + +```python + ┌───┐ +q_0: ──────■──────┤ H ├ + ┌─────┴─────┐└───┘ +q_1: ┤ RX(-1.57) ├───── + └───────────┘ +``` + +### iso + + + +`iso(isometry, q_input, q_ancillas_for_output, q_ancillas_zero=None, q_ancillas_dirty=None, epsilon=1e-10)` + +Attach an arbitrary isometry from m to n qubits to a circuit. In particular, this allows to attach arbitrary unitaries on n qubits (m=n) or to prepare any state on n qubits (m=0). The decomposition used here was introduced by Iten et al. in [https://arxiv.org/abs/1501.06911](https://arxiv.org/abs/1501.06911). + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.iso()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.Isometry to the circuit. + + +**Parameters** + +* **isometry** (*ndarray*) – an isometry from m to n qubits, i.e., a (complex) ndarray of dimension 2^n×2^m with orthonormal columns (given in the computational basis specified by the order of the ancillas and the input qubits, where the ancillas are considered to be more significant than the input qubits.). +* **q\_input** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of m qubits where the input to the isometry is fed in (empty list for state preparation). +* **q\_ancillas\_for\_output** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of n-m ancilla qubits that are used for the output of the isometry and which are assumed to start in the zero state. The qubits are listed with increasing significance. +* **q\_ancillas\_zero** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of ancilla qubits which are assumed to start in the zero state. Default is q\_ancillas\_zero = None. +* **q\_ancillas\_dirty** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of ancilla qubits which can start in an arbitrary state. Default is q\_ancillas\_dirty = None. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – error tolerance of calculations. Default is epsilon = \_EPS. + +**Returns** + +the isometry is attached to the quantum circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the array is not an isometry of the correct size corresponding to the provided number of qubits. + +### isometry + + + +`isometry(isometry, q_input, q_ancillas_for_output, q_ancillas_zero=None, q_ancillas_dirty=None, epsilon=1e-10)` + +Attach an arbitrary isometry from m to n qubits to a circuit. In particular, this allows to attach arbitrary unitaries on n qubits (m=n) or to prepare any state on n qubits (m=0). The decomposition used here was introduced by Iten et al. in [https://arxiv.org/abs/1501.06911](https://arxiv.org/abs/1501.06911). + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.iso()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.Isometry to the circuit. + + +**Parameters** + +* **isometry** (*ndarray*) – an isometry from m to n qubits, i.e., a (complex) ndarray of dimension 2^n×2^m with orthonormal columns (given in the computational basis specified by the order of the ancillas and the input qubits, where the ancillas are considered to be more significant than the input qubits.). +* **q\_input** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of m qubits where the input to the isometry is fed in (empty list for state preparation). +* **q\_ancillas\_for\_output** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of n-m ancilla qubits that are used for the output of the isometry and which are assumed to start in the zero state. The qubits are listed with increasing significance. +* **q\_ancillas\_zero** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of ancilla qubits which are assumed to start in the zero state. Default is q\_ancillas\_zero = None. +* **q\_ancillas\_dirty** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of ancilla qubits which can start in an arbitrary state. Default is q\_ancillas\_dirty = None. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – error tolerance of calculations. Default is epsilon = \_EPS. + +**Returns** + +the isometry is attached to the quantum circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the array is not an isometry of the correct size corresponding to the provided number of qubits. + +### iswap + + + +`iswap(qubit1, qubit2)` + +Apply [`iSwapGate`](qiskit.circuit.library.iSwapGate "qiskit.circuit.library.iSwapGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### mcp + + + +`mcp(lam, control_qubits, target_qubit)` + +Apply [`MCPhaseGate`](qiskit.circuit.library.MCPhaseGate "qiskit.circuit.library.MCPhaseGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **lam** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The angle of the rotation. +* **control\_qubits** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – The qubits used as the controls. +* **target\_qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) targeted by the gate. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### mcrx + + + +`mcrx(theta, q_controls, q_target, use_basis_gates=False)` + +Apply Multiple-Controlled X rotation gate + +**Parameters** + +* **self** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The QuantumCircuit object to apply the mcrx gate on. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – angle theta +* **q\_controls** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*)*) – The list of control qubits +* **q\_target** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The target qubit +* **use\_basis\_gates** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – use p, u, cx + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – parameter errors + +### mcry + + + +`mcry(theta, q_controls, q_target, q_ancillae=None, mode=None, use_basis_gates=False)` + +Apply Multiple-Controlled Y rotation gate + +**Parameters** + +* **self** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The QuantumCircuit object to apply the mcry gate on. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – angle theta +* **q\_controls** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*)*) – The list of control qubits +* **q\_target** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The target qubit +* **q\_ancillae** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*(*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*)*) – The list of ancillary qubits. +* **mode** (*string*) – The implementation mode to use +* **use\_basis\_gates** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – use p, u, cx + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – parameter errors + +### mcrz + + + +`mcrz(lam, q_controls, q_target, use_basis_gates=False)` + +Apply Multiple-Controlled Z rotation gate + +**Parameters** + +* **self** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The QuantumCircuit object to apply the mcrz gate on. +* **lam** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – angle lambda +* **q\_controls** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*)*) – The list of control qubits +* **q\_target** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The target qubit +* **use\_basis\_gates** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – use p, u, cx + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – parameter errors + +### mct + + + +`mct(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla')` + +Apply [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.MCXGate"). + +The multi-cX gate can be implemented using different techniques, which use different numbers of ancilla qubits and have varying circuit depth. These modes are: + +* `'noancilla'`: Requires 0 ancilla qubits. +* `'recursion'`: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0. +* `'v-chain'`: Requires 2 less ancillas than the number of control qubits. +* `'v-chain-dirty'`: Same as for the clean ancillas (but the circuit will be longer). + +For the full matrix form of this gate, see the underlying gate documentation. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.mct()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Use QuantumCircuit.mcx as direct replacement. + + +**Parameters** + +* **control\_qubits** (*Sequence\[QubitSpecifier]*) – The qubits used as the controls. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **ancilla\_qubits** (*QubitSpecifier | Sequence\[QubitSpecifier] | None*) – The qubits used as the ancillae, if the mode requires them. +* **mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The choice of mode, explained further above. + +**Returns** + +A handle to the instructions created. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if the given mode is not known, or if too few ancilla qubits are passed. +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – if no ancilla qubits are passed, but some are needed. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + + + QuantumCircuit.mcx: the same gate with a different name. + + +### mcx + + + +`mcx(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla')` + +Apply [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.MCXGate"). + +The multi-cX gate can be implemented using different techniques, which use different numbers of ancilla qubits and have varying circuit depth. These modes are: + +* `'noancilla'`: Requires 0 ancilla qubits. +* `'recursion'`: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0. +* `'v-chain'`: Requires 2 less ancillas than the number of control qubits. +* `'v-chain-dirty'`: Same as for the clean ancillas (but the circuit will be longer). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubits** (*Sequence\[QubitSpecifier]*) – The qubits used as the controls. +* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate. +* **ancilla\_qubits** (*QubitSpecifier | Sequence\[QubitSpecifier] | None*) – The qubits used as the ancillae, if the mode requires them. +* **mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The choice of mode, explained further above. + +**Returns** + +A handle to the instructions created. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if the given mode is not known, or if too few ancilla qubits are passed. +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – if no ancilla qubits are passed, but some are needed. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### measure + + + +`measure(qubit, cbit)` + +Measure a quantum bit (`qubit`) in the Z basis into a classical bit (`cbit`). + +When a quantum state is measured, a qubit is projected in the computational (Pauli Z) basis to either $\lvert 0 \rangle$ or $\lvert 1 \rangle$. The classical bit `cbit` indicates the result of that projection as a `0` or a `1` respectively. This operation is non-reversible. + +**Parameters** + +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – qubit(s) to measure. +* **cbit** ([*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit") *|*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.classicalregister.ClassicalRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – classical bit(s) to place the measurement result(s) in. + +**Returns** + +handle to the added instructions. + +**Return type** + +[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if arguments have bad format. + +**Examples** + +In this example, a qubit is measured and the result of that measurement is stored in the classical bit (usually expressed in diagrams as a double line): + +```python +from qiskit import QuantumCircuit +circuit = QuantumCircuit(1, 1) +circuit.h(0) +circuit.measure(0, 0) +circuit.draw() +``` + +```python + ┌───┐┌─┐ + q: ┤ H ├┤M├ + └───┘└╥┘ +c: 1/══════╩═ + 0 +``` + +It is possible to call `measure` with lists of `qubits` and `cbits` as a shortcut for one-to-one measurement. These two forms produce identical results: + +```python +circuit = QuantumCircuit(2, 2) +circuit.measure([0,1], [0,1]) +``` + +```python +circuit = QuantumCircuit(2, 2) +circuit.measure(0, 0) +circuit.measure(1, 1) +``` + +Instead of lists, you can use [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") and [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") under the same logic. + +```python +from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister +qreg = QuantumRegister(2, "qreg") +creg = ClassicalRegister(2, "creg") +circuit = QuantumCircuit(qreg, creg) +circuit.measure(qreg, creg) +``` + +This is equivalent to: + +```python +circuit = QuantumCircuit(qreg, creg) +circuit.measure(qreg[0], creg[0]) +circuit.measure(qreg[1], creg[1]) +``` + +### measure\_active + + + +`measure_active(inplace=True)` + +Adds measurement to all non-idle qubits. Creates a new ClassicalRegister with a size equal to the number of non-idle qubits being measured. + +Returns a new circuit with measurements if inplace=False. + +**Parameters** + +**inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – All measurements inplace or return new circuit. + +**Returns** + +Returns circuit with measurements when inplace = False. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### measure\_all + + + +`measure_all(inplace=True, add_bits=True)` + +Adds measurement to all qubits. + +By default, adds new classical bits in a [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") to store these measurements. If `add_bits=False`, the results of the measurements will instead be stored in the already existing classical bits, with qubit `n` being measured into classical bit `n`. + +Returns a new circuit with measurements if `inplace=False`. + +**Parameters** + +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – All measurements inplace or return new circuit. +* **add\_bits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to add new bits to store the results. + +**Returns** + +Returns circuit with measurements when `inplace=False`. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `add_bits=False` but there are not enough classical bits. + +### ms + + + +`ms(theta, qubits)` + +Apply [`MSGate`](qiskit.circuit.library.MSGate "qiskit.circuit.library.MSGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The angle of the rotation. +* **qubits** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – The qubits to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### num\_connected\_components + + + +`num_connected_components(unitary_only=False)` + +How many non-entangled subcircuits can the circuit be factored to. + +**Parameters** + +**unitary\_only** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Compute only unitary part of graph. + +**Returns** + +Number of connected components in circuit. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### num\_nonlocal\_gates + + + +`num_nonlocal_gates()` + +Return number of non-local gates (i.e. involving 2+ qubits). + +Conditional nonlocal gates are also included. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### num\_tensor\_factors + + + +`num_tensor_factors()` + +Computes the number of tensor factors in the unitary (quantum) part of the circuit only. + +**Notes** + +This is here for backwards compatibility, and will be removed in a future release of Qiskit. You should call num\_unitary\_factors instead. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### num\_unitary\_factors + + + +`num_unitary_factors()` + +Computes the number of tensor factors in the unitary (quantum) part of the circuit only. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### p + + + +`p(theta, qubit)` + +Apply [`PhaseGate`](qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – THe angle of the rotation. +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### pauli + + + +`pauli(pauli_string, qubits)` + +Apply [`PauliGate`](qiskit.circuit.library.PauliGate "qiskit.circuit.library.PauliGate"). + +**Parameters** + +* **pauli\_string** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A string representing the Pauli operator to apply, e.g. ‘XX’. +* **qubits** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – The qubits to apply this gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### power + + + +`power(power, matrix_power=False)` + +Raise this circuit to the power of `power`. + +If `power` is a positive integer and `matrix_power` is `False`, this implementation defaults to calling `repeat`. Otherwise, if the circuit is unitary, the matrix is computed to calculate the matrix power. + +**Parameters** + +* **power** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The power to raise this circuit to. +* **matrix\_power** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, the circuit is converted to a matrix and then the matrix power is computed. If False, and `power` is a positive integer, the implementation defaults to `repeat`. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the circuit needs to be converted to a gate but it is not unitary. + +**Returns** + +A circuit implementing this circuit raised to the power of `power`. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### prepare\_state + + + +`prepare_state(state, qubits=None, label=None, normalize=False)` + +Prepare qubits in a specific state. + +This class implements a state preparing unitary. Unlike [`Initialize`](qiskit.circuit.library.Initialize "qiskit.circuit.library.Initialize") it does not reset the qubits first. + +**Parameters** + +* **state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – + + * Statevector: Statevector to initialize to. + * str: labels of basis states of the Pauli eigenstates Z, X, Y. See [`Statevector.from_label()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label"). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to $|1\rangle$ and the qubit one to $|0\rangle$. + * list: vector of complex amplitudes to initialize to. + * int: an integer that is used as a bitmap indicating which qubits to initialize to $|1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $|1\rangle$ and qubit 1 to $|0\rangle$. + +* **qubits** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *or*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – + + * QuantumRegister: A list of qubits to be initialized \[Default: None]. + * Qubit: Single qubit to be initialized \[Default: None]. + * int: Index of qubit to be initialized \[Default: None]. + * list: Indexes of qubits to be initialized \[Default: None]. + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional label for the gate + +* **normalize** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to normalize an input array to a unit vector. + +**Returns** + +a handle to the instruction that was just initialized + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Examples** + +Prepare a qubit in the state $(|0\rangle - |1\rangle) / \sqrt{2}$. + +```python +import numpy as np +from qiskit import QuantumCircuit + +circuit = QuantumCircuit(1) +circuit.prepare_state([1/np.sqrt(2), -1/np.sqrt(2)], 0) +circuit.draw() +``` + +output: + +```python + ┌─────────────────────────────────────┐ +q_0: ┤ State Preparation(0.70711,-0.70711) ├ + └─────────────────────────────────────┘ +``` + +Prepare from a string two qubits in the state $|10\rangle$. The order of the labels is reversed with respect to qubit index. More information about labels for basis states are in [`Statevector.from_label()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label"). + +```python +import numpy as np +from qiskit import QuantumCircuit + +circuit = QuantumCircuit(2) +circuit.prepare_state('01', circuit.qubits) +circuit.draw() +``` + +output: + +```python + ┌─────────────────────────┐ +q_0: ┤0 ├ + │ State Preparation(0,1) │ +q_1: ┤1 ├ + └─────────────────────────┘ +``` + +Initialize two qubits from an array of complex amplitudes .. code-block: + +```python +import numpy as np +from qiskit import QuantumCircuit + +circuit = QuantumCircuit(2) +circuit.prepare_state([0, 1/np.sqrt(2), -1.j/np.sqrt(2), 0], circuit.qubits) +circuit.draw() +``` + +output: + +```python + ┌───────────────────────────────────────────┐ +q_0: ┤0 ├ + │ State Preparation(0,0.70711,-0.70711j,0) │ +q_1: ┤1 ├ + └───────────────────────────────────────────┘ +``` + +### qasm + + + +`qasm(formatted=False, filename=None, encoding=None)` + +Return OpenQASM 2.0 string. + + + **[`qasm2.dump()`](qasm2#qiskit.qasm2.dump "qiskit.qasm2.dump") and [`qasm2.dumps()`](qasm2#qiskit.qasm2.dumps "qiskit.qasm2.dumps")** + + The preferred entry points to the OpenQASM 2 export capabilities. These match the interface for other serialisers in Qiskit. + + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.qasm()` is deprecated as of qiskit 0.46. It will be removed in the 1.0.0 release. Instead use the qiskit.qasm2.dump() or qiskit.qasm2.dumps() function + + +**Parameters** + +* **formatted** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Return formatted OpenQASM 2.0 string. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Save OpenQASM 2.0 to file with name ‘filename’. +* **encoding** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optionally specify the encoding to use for the output file if `filename` is specified. By default this is set to the system’s default encoding (ie whatever `locale.getpreferredencoding()` returns) and can be set to any valid codec or alias from stdlib’s [codec module](https://docs.python.org/3/library/codecs.html#standard-encodings) + +**Returns** + +If formatted=False. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – If pygments is not installed and `formatted` is `True`. +* [**QASM2ExportError**](qasm2#qiskit.qasm2.QASM2ExportError "qiskit.qasm2.QASM2ExportError") – If circuit has free parameters. +* [**QASM2ExportError**](qasm2#qiskit.qasm2.QASM2ExportError "qiskit.qasm2.QASM2ExportError") – If an operation that has no OpenQASM 2 representation is encountered. + +### qbit\_argument\_conversion + + + +`qbit_argument_conversion(qubit_representation)` + +Converts several qubit representations (such as indexes, range, etc.) into a list of qubits. + +**Parameters** + +**qubit\_representation** (*Object*) – representation to expand + +**Returns** + +the resolved instances of the qubits. + +**Return type** + +List([Qubit](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) + +### qubit\_duration + + + +`qubit_duration(*qubits)` + +Return the duration between the start and stop time of the first and last instructions, excluding delays, over the supplied qubits. Its time unit is `self.unit`. + +**Parameters** + +**\*qubits** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubits within `self` to include. + +**Returns** + +Return the duration between the first start and last stop time of non-delay instructions + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### qubit\_start\_time + + + +`qubit_start_time(*qubits)` + +Return the start time of the first instruction, excluding delays, over the supplied qubits. Its time unit is `self.unit`. + +Return 0 if there are no instructions over qubits + +**Parameters** + +* **\*qubits** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubits within `self` to include. Integers are allowed for qubits, indicating +* **self.qubits.** (*indices of*) – + +**Returns** + +Return the start time of the first instruction, excluding delays, over the qubits + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `self` is a not-yet scheduled circuit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### qubit\_stop\_time + + + +`qubit_stop_time(*qubits)` + +Return the stop time of the last instruction, excluding delays, over the supplied qubits. Its time unit is `self.unit`. + +Return 0 if there are no instructions over qubits + +**Parameters** + +* **\*qubits** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubits within `self` to include. Integers are allowed for qubits, indicating +* **self.qubits.** (*indices of*) – + +**Returns** + +Return the stop time of the last instruction, excluding delays, over the qubits + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `self` is a not-yet scheduled circuit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### r + + + +`r(theta, phi, qubit)` + +Apply [`RGate`](qiskit.circuit.library.RGate "qiskit.circuit.library.RGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The angle of the rotation. +* **phi** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The angle of the axis of rotation in the x-y plane. +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### rcccx + + + +`rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)` + +Apply [`RC3XGate`](qiskit.circuit.library.RC3XGate "qiskit.circuit.library.RC3XGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the first control. +* **control\_qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the second control. +* **control\_qubit3** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the third control. +* **target\_qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) targeted by the gate. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### rccx + + + +`rccx(control_qubit1, control_qubit2, target_qubit)` + +Apply [`RCCXGate`](qiskit.circuit.library.RCCXGate "qiskit.circuit.library.RCCXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **control\_qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the first control. +* **control\_qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the second control. +* **target\_qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) targeted by the gate. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### remove\_final\_measurements + + + +`remove_final_measurements(inplace=True)` + +Removes final measurements and barriers on all qubits if they are present. Deletes the classical registers that were used to store the values from these measurements that become idle as a result of this operation, and deletes classical bits that are referenced only by removed registers, or that aren’t referenced at all but have become idle as a result of this operation. + +Measurements and barriers are considered final if they are followed by no other operations (aside from other measurements or barriers.) + +**Parameters** + +**inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – All measurements removed inplace or return new circuit. + +**Returns** + +Returns the resulting circuit when `inplace=False`, else None. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### repeat + + + +`repeat(reps)` + +Repeat this circuit `reps` times. + +**Parameters** + +**reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – How often this circuit should be repeated. + +**Returns** + +A circuit containing `reps` repetitions of this circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### reset + + + +`reset(qubit)` + +Reset the quantum bit(s) to their default state. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – qubit(s) to reset. + +**Returns** + +handle to the added instruction. + +**Return type** + +[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### reverse\_bits + + + +`reverse_bits()` + +Return a circuit with the opposite order of wires. + +The circuit is “vertically” flipped. If a circuit is defined over multiple registers, the resulting circuit will have the same registers but with their order flipped. + +This method is useful for converting a circuit written in little-endian convention to the big-endian equivalent, and vice versa. + +**Returns** + +the circuit with reversed bit order. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Examples** + +input: + +```python + ┌───┐ +a_0: ┤ H ├──■───────────────── + └───┘┌─┴─┐ +a_1: ─────┤ X ├──■──────────── + └───┘┌─┴─┐ +a_2: ──────────┤ X ├──■─────── + └───┘┌─┴─┐ +b_0: ───────────────┤ X ├──■── + └───┘┌─┴─┐ +b_1: ────────────────────┤ X ├ + └───┘ +``` + +output: + +```python + ┌───┐ +b_0: ────────────────────┤ X ├ + ┌───┐└─┬─┘ +b_1: ───────────────┤ X ├──■── + ┌───┐└─┬─┘ +a_0: ──────────┤ X ├──■─────── + ┌───┐└─┬─┘ +a_1: ─────┤ X ├──■──────────── + ┌───┐└─┬─┘ +a_2: ┤ H ├──■───────────────── + └───┘ +``` + +### reverse\_ops + + + +`reverse_ops()` + +Reverse the circuit by reversing the order of instructions. + +This is done by recursively reversing all instructions. It does not invert (adjoint) any gate. + +**Returns** + +the reversed circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Examples** + +input: + +```python + ┌───┐ +q_0: ┤ H ├─────■────── + └───┘┌────┴─────┐ +q_1: ─────┤ RX(1.57) ├ + └──────────┘ +``` + +output: + +```python + ┌───┐ +q_0: ─────■──────┤ H ├ + ┌────┴─────┐└───┘ +q_1: ┤ RX(1.57) ├───── + └──────────┘ +``` + +### rv + + + +`rv(vx, vy, vz, qubit)` + +Apply [`RVGate`](qiskit.circuit.library.RVGate "qiskit.circuit.library.RVGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +Rotation around an arbitrary rotation axis $v$, where $|v|$ is the angle of rotation in radians. + +**Parameters** + +* **vx** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – x-component of the rotation axis. +* **vy** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – y-component of the rotation axis. +* **vz** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – z-component of the rotation axis. +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### rx + + + +`rx(theta, qubit, label=None)` + +Apply [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The rotation angle of the gate. +* **qubit** (*QubitSpecifier*) – The qubit(s) to apply the gate to. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### rxx + + + +`rxx(theta, qubit1, qubit2)` + +Apply [`RXXGate`](qiskit.circuit.library.RXXGate "qiskit.circuit.library.RXXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The angle of the rotation. +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### ry + + + +`ry(theta, qubit, label=None)` + +Apply [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.RYGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** (*ParameterValueType*) – The rotation angle of the gate. +* **qubit** (*QubitSpecifier*) – The qubit(s) to apply the gate to. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### ryy + + + +`ryy(theta, qubit1, qubit2)` + +Apply [`RYYGate`](qiskit.circuit.library.RYYGate "qiskit.circuit.library.RYYGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rotation angle of the gate. +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### rz + + + +`rz(phi, qubit)` + +Apply [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **phi** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rotation angle of the gate. +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### rzx + + + +`rzx(theta, qubit1, qubit2)` + +Apply [`RZXGate`](qiskit.circuit.library.RZXGate "qiskit.circuit.library.RZXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rotation angle of the gate. +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### rzz + + + +`rzz(theta, qubit1, qubit2)` + +Apply [`RZZGate`](qiskit.circuit.library.RZZGate "qiskit.circuit.library.RZZGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rotation angle of the gate. +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### s + + + +`s(qubit)` + +Apply [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### sdg + + + +`sdg(qubit)` + +Apply [`SdgGate`](qiskit.circuit.library.SdgGate "qiskit.circuit.library.SdgGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### size + + + +`size(filter_function=>)` + +Returns total number of instructions in circuit. + +**Parameters** + +**filter\_function** (*callable*) – a function to filter out some instructions. Should take as input a tuple of (Instruction, list(Qubit), list(Clbit)). By default filters out “directives”, such as barrier or snapshot. + +**Returns** + +Total number of gate operations. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### snapshot + + + +`snapshot(label, snapshot_type='statevector', qubits=None, params=None)` + +Take a statevector snapshot of the internal simulator representation. Works on all qubits, and prevents reordering (like barrier). + +For other types of snapshots use the Snapshot extension directly. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.snapshot()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. The Snapshot instruction has been superseded by Qiskit Aer’s save instructions, see [https://qiskit.org/ecosystem/aer/apidocs/aer\_library.html#saving-simulator-data](https://qiskit.org/ecosystem/aer/apidocs/aer_library.html#saving-simulator-data). + + +**Parameters** + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a snapshot label to report the result. +* **snapshot\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the type of the snapshot. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – the qubits to apply snapshot to \[Default: None]. +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – the parameters for snapshot\_type \[Default: None]. + +**Returns** + +with attached command + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**ExtensionError**](extensions#qiskit.extensions.ExtensionError "qiskit.extensions.ExtensionError") – malformed command + +### squ + + + +`squ(unitary_matrix, qubit, mode='ZYZ', up_to_diagonal=False)` + +Decompose an arbitrary 2\*2 unitary into three rotation gates. + +Note that the decomposition is up to a global phase shift. (This is a well known decomposition which can be found for example in Nielsen and Chuang’s book “Quantum computation and quantum information”.) + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.squ()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Instead, use the QuantumCircuit.unitary method. + + +**Parameters** + +* **unitary\_matrix** (*ndarray*) – 2\*2 unitary (given as a (complex) ndarray). +* **qubit** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *or*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The qubit which the gate is acting on. +* **mode** (*string*) – determines the used decomposition by providing the rotation axes. The allowed modes are: “ZYZ” (default) +* **up\_to\_diagonal** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if set to True, the single-qubit unitary is decomposed up to a diagonal matrix, i.e. a unitary u’ is implemented such that there exists a 2\*2 diagonal gate d with u = d.dot(u’) + +**Returns** + +The single-qubit unitary instruction attached to the circuit. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the format is wrong; if the array u is not unitary + +### swap + + + +`swap(qubit1, qubit2)` + +Apply [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits to apply the gate to. +* **qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### switch + +### switch + + + +`switch(target: Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int], cases: None, qubits: None, clbits: None, *, label: str | None) → qiskit.circuit.controlflow.switch_case.SwitchContext` + + + +`switch(target: Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int], cases: Iterable[Tuple[Any, QuantumCircuit]], qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None) → InstructionSet` + +Create a `switch`/`case` structure on this circuit. + +There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a [`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp") with the given case structure. If `cases` (and `qubits` and `clbits`) are *not* passed, then this acts as a context manager, which will automatically build a [`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp") when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you. + +Example usage: + +```python +from qiskit.circuit import QuantumCircuit, ClassicalRegister, QuantumRegister +qreg = QuantumRegister(3) +creg = ClassicalRegister(3) +qc = QuantumCircuit(qreg, creg) +qc.h([0, 1, 2]) +qc.measure([0, 1, 2], [0, 1, 2]) + +with qc.switch(creg) as case: + with case(0): + qc.x(0) + with case(1, 2): + qc.z(1) + with case(case.DEFAULT): + qc.cx(0, 1) +``` + +**Parameters** + +* **target** (*Union\[*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – The classical value to switch one. This must be integer-like. +* **cases** (*Iterable\[Tuple\[*[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*,* [*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]]*) – A sequence of case specifiers. Each tuple defines one case body (the second item). The first item of the tuple can be either a single integer value, the special value [`CASE_DEFAULT`](circuit#qiskit.circuit.CASE_DEFAULT "qiskit.circuit.CASE_DEFAULT"), or a tuple of several integer values. Each of the integer values will be tried in turn; control will then pass to the body corresponding to the first match. [`CASE_DEFAULT`](circuit#qiskit.circuit.CASE_DEFAULT "qiskit.circuit.CASE_DEFAULT") matches all possible values. Omit in context-manager form. +* **qubits** (*Sequence\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – The circuit qubits over which all case bodies execute. Omit in context-manager form. +* **clbits** (*Sequence\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – The circuit clbits over which all case bodies execute. Omit in context-manager form. +* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – The string label of the instruction in the circuit. + +**Returns** + +If used in context-manager mode, then this should be used as a `with` resource, which will return an object that can be repeatedly entered to produce cases for the switch statement. If the full form is used, then this returns a handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or SwitchCaseContext + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used. + +### sx + + + +`sx(qubit)` + +Apply [`SXGate`](qiskit.circuit.library.SXGate "qiskit.circuit.library.SXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### sxdg + + + +`sxdg(qubit)` + +Apply [`SXdgGate`](qiskit.circuit.library.SXdgGate "qiskit.circuit.library.SXdgGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### t + + + +`t(qubit)` + +Apply [`TGate`](qiskit.circuit.library.TGate "qiskit.circuit.library.TGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### tdg + + + +`tdg(qubit)` + +Apply [`TdgGate`](qiskit.circuit.library.TdgGate "qiskit.circuit.library.TdgGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### tensor + + + +`tensor(other, inplace=False)` + +Tensor `self` with `other`. + +Remember that in the little-endian convention the leftmost operation will be at the bottom of the circuit. See also [the docs](https://docs.quantum-computing.ibm.com/build/circuit-construction) for more information. + +```python + ┌────────┐ ┌─────┐ ┌─────┐ +q_0: ┤ bottom ├ ⊗ q_0: ┤ top ├ = q_0: ─┤ top ├── + └────────┘ └─────┘ ┌┴─────┴─┐ + q_1: ┤ bottom ├ + └────────┘ +``` + +**Parameters** + +* **other** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The other circuit to tensor this circuit with. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, modify the object. Otherwise return composed circuit. + +**Return type** + +[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") | None + +**Examples** + +```python +from qiskit import QuantumCircuit +top = QuantumCircuit(1) +top.x(0); +bottom = QuantumCircuit(2) +bottom.cry(0.2, 0, 1); +tensored = bottom.tensor(top) +tensored.draw('mpl') +``` + +![../\_images/qiskit-circuit-QuantumCircuit-6.png](/images/api/qiskit/0.46/qiskit-circuit-QuantumCircuit-6.png) + +**Returns** + +The tensored circuit (returns None if inplace==True). + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### to\_gate + + + +`to_gate(parameter_map=None, label=None)` + +Create a Gate out of this circuit. + +**Parameters** + +* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the gate. If None, existing circuit parameters will also parameterize the gate. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional gate label. + +**Returns** + +a composite gate encapsulating this circuit (can be decomposed back) + +**Return type** + +[Gate](qiskit.circuit.Gate "qiskit.circuit.Gate") + +### to\_instruction + + + +`to_instruction(parameter_map=None, label=None)` + +Create an Instruction out of this circuit. + +**Parameters** + +* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the instruction. If None, existing circuit parameters will also parameterize the instruction. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional gate label. + +**Returns** + +a composite instruction encapsulating this circuit (can be decomposed back) + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### toffoli + + + +`toffoli(control_qubit1, control_qubit2, target_qubit)` + +Apply [`CCXGate`](qiskit.circuit.library.CCXGate "qiskit.circuit.library.CCXGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.toffoli()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0.0 release. Use QuantumCircuit.ccx as direct replacement. + + +**Parameters** + +* **control\_qubit1** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the first control. +* **control\_qubit2** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) used as the second control. +* **target\_qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) targeted by the gate. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + + + QuantumCircuit.ccx: the same gate with a different name. + + +### u + + + +`u(theta, phi, lam, qubit)` + +Apply [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The $\theta$ rotation angle of the gate. +* **phi** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The $\phi$ rotation angle of the gate. +* **lam** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The $\lambda$ rotation angle of the gate. +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### uc + + + +`uc(gate_list, q_controls, q_target, up_to_diagonal=False)` + +Attach a uniformly controlled gates (also called multiplexed gates) to a circuit. + +The decomposition was introduced by Bergholm et al. in [https://arxiv.org/pdf/quant-ph/0410066.pdf](https://arxiv.org/pdf/quant-ph/0410066.pdf). + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.uc()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.UCGate to the circuit. + + +**Parameters** + +* **gate\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[ndarray]*) – list of two qubit unitaries \[U\_0,…,U\_\{2^k-1}], where each single-qubit unitary U\_i is a given as a 2\*2 array +* **q\_controls** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[(*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")*,*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*)]*) – list of k control qubits. The qubits are ordered according to their significance in the computational basis. For example if q\_controls=\[q\[1],q\[2]] (with q = QuantumRegister(2)), the unitary U\_0 is performed if q\[1] and q\[2] are in the state zero, U\_1 is performed if q\[2] is in the state zero and q\[1] is in the state one, and so on +* **q\_target** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *|*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*(*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*)*) – target qubit, where we act on with the single-qubit gates. +* **up\_to\_diagonal** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to True, the uniformly controlled gate is decomposed up to a diagonal gate, i.e. a unitary u’ is implemented such that there exists a diagonal gate d with u = d.dot(u’), where the unitary u describes the uniformly controlled gate + +**Returns** + +the uniformly controlled gate is attached to the circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the list number of control qubits does not correspond to the provided number of single-qubit unitaries; if an input is of the wrong type + +### ucrx + + + +`ucrx(angle_list, q_controls, q_target)` + +Attach a uniformly controlled (also called multiplexed) Rx rotation gate to a circuit. + +The decomposition is base on [https://arxiv.org/pdf/quant-ph/0406176.pdf](https://arxiv.org/pdf/quant-ph/0406176.pdf) by Shende et al. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.ucrx()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.UCRXGate to the circuit. + + +**Parameters** + +* **angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – list of (real) rotation angles $[a_0,...,a_{2^k-1}]$ +* **q\_controls** (*Sequence\[QubitSpecifier]*) – list of k control qubits (or empty list if no controls). The control qubits are ordered according to their significance in increasing order: For example if `q_controls=[q[0],q[1]]` (with `q = QuantumRegister(2)`), the rotation `Rx(a_0)` is performed if `q[0]` and `q[1]` are in the state zero, the rotation `Rx(a_1)` is performed if `q[0]` is in the state one and `q[1]` is in the state zero, and so on +* **q\_target** (*QubitSpecifier*) – target qubit, where we act on with the single-qubit rotation gates + +**Returns** + +the uniformly controlled rotation gate is attached to the circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the list number of control qubits does not correspond to the provided number of single-qubit unitaries; if an input is of the wrong type + +### ucry + + + +`ucry(angle_list, q_controls, q_target)` + +Attach a uniformly controlled (also called multiplexed) Ry rotation gate to a circuit. + +The decomposition is base on [https://arxiv.org/pdf/quant-ph/0406176.pdf](https://arxiv.org/pdf/quant-ph/0406176.pdf) by Shende et al. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.ucry()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.UCRYGate to the circuit. + + +**Parameters** + +* **angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – list of (real) rotation angles $[a_0,...,a_{2^k-1}]$ +* **q\_controls** (*Sequence\[QubitSpecifier]*) – list of k control qubits (or empty list if no controls). The control qubits are ordered according to their significance in increasing order: For example if `q_controls=[q[0],q[1]]` (with `q = QuantumRegister(2)`), the rotation `Ry(a_0)` is performed if `q[0]` and `q[1]` are in the state zero, the rotation `Ry(a_1)` is performed if `q[0]` is in the state one and `q[1]` is in the state zero, and so on +* **q\_target** (*QubitSpecifier*) – target qubit, where we act on with the single-qubit rotation gates + +**Returns** + +the uniformly controlled rotation gate is attached to the circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the list number of control qubits does not correspond to the provided number of single-qubit unitaries; if an input is of the wrong type + +### ucrz + + + +`ucrz(angle_list, q_controls, q_target)` + +Attach a uniformly controlled (also called multiplexed) Rz rotation gate to a circuit. + +The decomposition is base on [https://arxiv.org/pdf/quant-ph/0406176.pdf](https://arxiv.org/pdf/quant-ph/0406176.pdf) by Shende et al. + + + The method `qiskit.circuit.quantumcircuit.QuantumCircuit.ucrz()` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0.0 release. Instead, append a qiskit.circuit.library.UCRZGate to the circuit. + + +**Parameters** + +* **angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – list of (real) rotation angles $[a_0,...,a_{2^k-1}]$ +* **q\_controls** (*Sequence\[QubitSpecifier]*) – list of k control qubits (or empty list if no controls). The control qubits are ordered according to their significance in increasing order: For example if `q_controls=[q[0],q[1]]` (with `q = QuantumRegister(2)`), the rotation `Rz(a_0)` is performed if `q[0]` and `q[1]` are in the state zero, the rotation `Rz(a_1)` is performed if `q[0]` is in the state one and `q[1]` is in the state zero, and so on +* **q\_target** (*QubitSpecifier*) – target qubit, where we act on with the single-qubit rotation gates + +**Returns** + +the uniformly controlled rotation gate is attached to the circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the list number of control qubits does not correspond to the provided number of single-qubit unitaries; if an input is of the wrong type + +### unitary + + + +`unitary(obj, qubits, label=None)` + +Apply unitary gate specified by `obj` to `qubits`. + +**Parameters** + +* **obj** (*np.ndarray |* [*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate") *| BaseOperator*) – Unitary operator. +* **qubits** (*Sequence\[QubitSpecifier]*) – The circuit qubits to apply the transformation to. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Unitary name for backend \[Default: None]. + +**Returns** + +The quantum circuit. + +**Return type** + +[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Example** + +Apply a gate specified by a unitary matrix to a quantum circuit + +```python +from qiskit import QuantumCircuit +matrix = [[0, 0, 0, 1], + [0, 0, 1, 0], + [1, 0, 0, 0], + [0, 1, 0, 0]] +circuit = QuantumCircuit(2) +circuit.unitary(matrix, [0, 1]) +``` + +### while\_loop + +### while\_loop + + + +`while_loop(condition: tuple[ClassicalRegister | Clbit, int] | expr.Expr, body: None, qubits: None, clbits: None, *, label: str | None) → qiskit.circuit.controlflow.while_loop.WhileLoopContext` + + + +`while_loop(condition: tuple[ClassicalRegister | Clbit, int] | expr.Expr, body: QuantumCircuit, qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None) → InstructionSet` + +Create a `while` loop on this circuit. + +There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a `WhileLoopOp` with the given `body`. If `body` (and `qubits` and `clbits`) are *not* passed, then this acts as a context manager, which will automatically build a `WhileLoopOp` when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you. + +Example usage: + +```python +from qiskit.circuit import QuantumCircuit, Clbit, Qubit +bits = [Qubit(), Qubit(), Clbit()] +qc = QuantumCircuit(bits) + +with qc.while_loop((bits[2], 0)): + qc.h(0) + qc.cx(0, 1) + qc.measure(0, 0) +``` + +**Parameters** + +* **condition** (*Tuple\[Union\[*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – An equality condition to be checked prior to executing `body`. The left-hand side of the condition must be a [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") or a [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit"), and the right-hand side must be an integer or boolean. +* **body** (*Optional\[*[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The loop body to be repeatedly executed. Omit this to use the context-manager mode. +* **qubits** (*Optional\[Sequence\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]]*) – The circuit qubits over which the loop body should be run. Omit this to use the context-manager mode. +* **clbits** (*Optional\[Sequence\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]]*) – The circuit clbits over which the loop body should be run. Omit this to use the context-manager mode. +* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – The string label of the instruction in the circuit. + +**Returns** + +If used in context-manager mode, then this should be used as a `with` resource, which will infer the block content and operands on exit. If the full form is used, then this returns a handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or WhileLoopContext + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used. + +### width + + + +`width()` + +Return number of qubits plus clbits in circuit. + +**Returns** + +Width of circuit. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### x + + + +`x(qubit, label=None)` + +Apply [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +* **qubit** (*QubitSpecifier*) – The qubit(s) to apply the gate to. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The string label of the gate in the circuit. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") + +### y + + + +`y(qubit)` + +Apply [`YGate`](qiskit.circuit.library.YGate "qiskit.circuit.library.YGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + +### z + + + +`z(qubit)` + +Apply [`ZGate`](qiskit.circuit.library.ZGate "qiskit.circuit.library.ZGate"). + +For the full matrix form of this gate, see the underlying gate documentation. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.12)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit(s) to apply the gate to. + +**Returns** + +A handle to the instructions created. + +**Return type** + +[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.QuantumRegister.md b/docs/api/qiskit/0.46/qiskit.circuit.QuantumRegister.md new file mode 100644 index 00000000000..009b411b508 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.QuantumRegister.md @@ -0,0 +1,90 @@ +--- +title: QuantumRegister +description: API reference for qiskit.circuit.QuantumRegister +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.QuantumRegister +--- + +# QuantumRegister + + + +`qiskit.circuit.QuantumRegister(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/quantumregister.py "view source code") + +Bases: [`Register`](qiskit.circuit.Register "qiskit.circuit.register.Register") + +Implement a quantum register. + +Create a new generic register. + +Either the `size` or the `bits` argument must be provided. If `size` is not None, the register will be pre-populated with bits of the correct type. + +**Parameters** + +* **size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The number of bits to include in the register. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. The name of the register. If not provided, a unique name will be auto-generated from the register type. +* **bits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – Optional. A list of Bit() instances to be used to populate the register. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if both the `size` and `bits` arguments are provided, or if neither are. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `size` is not valid. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `name` is not a valid name according to the OpenQASM spec. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained duplicated bits. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained bits of an incorrect type. + +## Attributes + + + +### instances\_counter + +`= count(6)` + + + +### name + +Get the register name. + + + +### name\_format + +`= re.compile('[a-z][a-zA-Z0-9_]*')` + + + +### prefix + +`= 'q'` + + + +### size + +Get the register size. + +## Methods + +### index + + + +`index(bit)` + +Find the index of the provided bit within this register. + +### qasm + + + +`qasm()` + +Return OPENQASM string for this register. + + + The method `qiskit.circuit.quantumregister.QuantumRegister.qasm()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Qubit.md b/docs/api/qiskit/0.46/qiskit.circuit.Qubit.md new file mode 100644 index 00000000000..4eec17a136b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Qubit.md @@ -0,0 +1,55 @@ +--- +title: Qubit +description: API reference for qiskit.circuit.Qubit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Qubit +--- + +# Qubit + + + +`qiskit.circuit.Qubit(register=None, index=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/quantumregister.py "view source code") + +Bases: [`Bit`](qiskit.circuit.Bit "qiskit.circuit.bit.Bit") + +Implement a quantum bit. + +Creates a qubit. + +**Parameters** + +* **register** ([*QuantumRegister*](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")) – Optional. A quantum register containing the bit. +* **index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The index of the bit in its containing register. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the provided register is not a valid [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") + +## Attributes + + + +### index + +Get the index of an old-style bit in the register that owns it. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.index` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + + + +### register + +Get the register of an old-style bit. + +In modern Qiskit Terra (version 0.17+), bits are the fundamental object and registers are aliases to collections of bits. A bit can be in many registers depending on the circuit, so a single containing register is no longer a property of a bit. It is an error to access this attribute on bits that were not constructed as “owned” by a register. + + + The property `qiskit.circuit.bit.Bit.register` is deprecated as of qiskit-terra 0.17. It will be removed in the Qiskit 1.0 release. Instead, use `find_bit()` to find all the containing registers within a circuit and the index of the bit within the circuit. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.Register.md b/docs/api/qiskit/0.46/qiskit.circuit.Register.md new file mode 100644 index 00000000000..6b95a843580 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.Register.md @@ -0,0 +1,88 @@ +--- +title: Register +description: API reference for qiskit.circuit.Register +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.Register +--- + +# Register + + + +`qiskit.circuit.Register(size=None, name=None, bits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/register.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Implement a generic register. + + + This class should not be instantiated directly. This is just a superclass for [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") and [`QuantumRegister`](qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister"). + + +Create a new generic register. + +Either the `size` or the `bits` argument must be provided. If `size` is not None, the register will be pre-populated with bits of the correct type. + +**Parameters** + +* **size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The number of bits to include in the register. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. The name of the register. If not provided, a unique name will be auto-generated from the register type. +* **bits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – Optional. A list of Bit() instances to be used to populate the register. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if both the `size` and `bits` arguments are provided, or if neither are. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `size` is not valid. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `name` is not a valid name according to the OpenQASM spec. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained duplicated bits. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `bits` contained bits of an incorrect type. + +## Attributes + + + +### bit\_type + +`= None` + + + +### instances\_counter + +`= count(0)` + + + +### name + +Get the register name. + + + +### name\_format + +`= re.compile('[a-z][a-zA-Z0-9_]*')` + + + +### prefix + +`= 'reg'` + + + +### size + +Get the register size. + +## Methods + +### index + + + +`index(bit)` + +Find the index of the provided bit within this register. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.SwitchCaseOp.md b/docs/api/qiskit/0.46/qiskit.circuit.SwitchCaseOp.md new file mode 100644 index 00000000000..3d24cb66b1a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.SwitchCaseOp.md @@ -0,0 +1,392 @@ +--- +title: SwitchCaseOp +description: API reference for qiskit.circuit.SwitchCaseOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.SwitchCaseOp +--- + +# SwitchCaseOp + + + +`qiskit.circuit.SwitchCaseOp(target, cases, *, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/switch_case.py "view source code") + +Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") + +A circuit operation that executes one particular circuit block based on matching a given `target` against an ordered list of `values`. The special value [`CASE_DEFAULT`](circuit#qiskit.circuit.CASE_DEFAULT "qiskit.circuit.CASE_DEFAULT") can be used to represent a default condition. + +This is the low-level interface for creating a switch-case statement; in general, the circuit method [`QuantumCircuit.switch()`](qiskit.circuit.QuantumCircuit#switch "qiskit.circuit.QuantumCircuit.switch") should be used as a context manager to access the builder interface. At the low level, you must ensure that all the circuit blocks contain equal numbers of qubits and clbits, and that the order the virtual bits of the containing circuit should be bound is the same for all blocks. This will likely mean that each circuit block is wider than its natural width, as each block must span the union of all the spaces covered by *any* of the blocks. + +**Parameters** + +* **target** ([*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit") *|*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") *|*[*expr.Expr*](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")) – the runtime value to switch on. +* **cases** (*Iterable\[Tuple\[Any,* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]]*) – an ordered iterable of the corresponding value of the `target` and the circuit block that should be executed if this is matched. There is no fall-through between blocks, and the order matters. + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.SwitchCaseOp.base_class "qiskit.circuit.SwitchCaseOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### blocks + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### cases + + + +`cases()` + +Return a lookup table from case labels to the circuit that would be executed in that case. This object is not generally suitable for creating a new [`SwitchCaseOp`](#qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp") because any keys that point to the same object will not be grouped. + + + **[`SwitchCaseOp.cases_specifier()`](#qiskit.circuit.SwitchCaseOp.cases_specifier "qiskit.circuit.SwitchCaseOp.cases_specifier")** + + An alternate method that produces its output in a suitable format for creating new [`SwitchCaseOp`](#qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp") instances. + + +### cases\_specifier + + + +`cases_specifier()` + +Return an iterable where each element is a 2-tuple whose first element is a tuple of jump values, and whose second is the single circuit block that is associated with those values. + +This is an abstract specification of the jump table suitable for creating new [`SwitchCaseOp`](#qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp") instances. + + + **[`SwitchCaseOp.cases()`](#qiskit.circuit.SwitchCaseOp.cases "qiskit.circuit.SwitchCaseOp.cases")** + + Create a lookup table that you can use for your own purposes to jump from values to the circuit that would be executed. + + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)"), [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")]] + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### replace\_blocks + + + +`replace_blocks(blocks)` + +Replace blocks and return new instruction. :param blocks: Tuple of QuantumCircuits to replace in instruction. + +**Returns** + +New ControlFlowOp with replaced blocks. + +**Return type** + +[*SwitchCaseOp*](#qiskit.circuit.SwitchCaseOp "qiskit.circuit.controlflow.switch_case.SwitchCaseOp") + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.WhileLoopOp.md b/docs/api/qiskit/0.46/qiskit.circuit.WhileLoopOp.md new file mode 100644 index 00000000000..f850b0a6671 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.WhileLoopOp.md @@ -0,0 +1,367 @@ +--- +title: WhileLoopOp +description: API reference for qiskit.circuit.WhileLoopOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.WhileLoopOp +--- + +# WhileLoopOp + + + +`qiskit.circuit.WhileLoopOp(condition, body, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/controlflow/while_loop.py "view source code") + +Bases: [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.controlflow.control_flow.ControlFlowOp") + +A circuit operation which repeatedly executes a subcircuit (`body`) until a condition (`condition`) evaluates as False. + +**Parameters** + +* **condition** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*ClassicalRegister*](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*expr.Expr*](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")) – A condition to be checked prior to executing `body`. Can be specified as either a tuple of a `ClassicalRegister` to be tested for equality with a given `int`, or as a tuple of a `Clbit` to be compared to either a `bool` or an `int`. +* **body** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The loop body to be repeatedly executed. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – An optional label for identifying the instruction. + +The classical bits used in `condition` must be a subset of those attached to `body`. + +**Circuit symbol:** + +```python + ┌─────────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 ├ + │ while_loop │ +q_2: ┤2 ├ + │ │ +c_0: ╡0 ╞ + └─────────────┘ +``` + +Create a new instruction. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – instruction name +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s qubit width +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – instruction’s clbit width +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*|ndarray|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – list of parameters +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – instruction’s duration. it must be integer if `unit` is ‘dt’ +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – time unit of duration +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for identifying the instruction. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – when the register is not in the correct format. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – when the optional label is provided, but it is not a string. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.WhileLoopOp.base_class "qiskit.circuit.WhileLoopOp.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that [`Instruction.name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") should be a more suitable discriminator in most situations. + + + +### blocks + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### replace\_blocks + + + +`replace_blocks(blocks)` + +Replace blocks and return new instruction. :param blocks: Tuple of QuantumCircuits to replace in instruction. + +**Returns** + +New ControlFlowOp with replaced blocks. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.BooleanExpression.md b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.BooleanExpression.md new file mode 100644 index 00000000000..7cc37760ed2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.BooleanExpression.md @@ -0,0 +1,487 @@ +--- +title: BooleanExpression +description: API reference for qiskit.circuit.classicalfunction.BooleanExpression +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.classicalfunction.BooleanExpression +--- + +# BooleanExpression + + + +`qiskit.circuit.classicalfunction.BooleanExpression(expression, name=None, var_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classicalfunction/boolean_expression.py "view source code") + +Bases: `ClassicalElement` + +The Boolean Expression gate. + +**Parameters** + +* **expression** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The logical expression string. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. Instruction gate name. Otherwise part of the expression is going to be used. +* **var\_order** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list with the order in which variables will be created. (default: by appearance) + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.classicalfunction.BooleanExpression.base_class "qiskit.circuit.classicalfunction.BooleanExpression.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of quantum bit arguments. +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return controlled version of gate. See [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") for usage. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of controls to add to gate (default: `1`) +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – optional gate label +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The control state in decimal or as a bitstring (e.g. `'111'`). If `None`, use `2**num_ctrl_qubits-1`. + +**Returns** + +Controlled version of gate. This default algorithm uses `num_ctrl_qubits-1` ancilla qubits so returns a gate of size `num_qubits + 2*num_ctrl_qubits - 1`. + +**Return type** + +[qiskit.circuit.ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – unrecognized mode or invalid ctrl\_state + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### from\_dimacs\_file + + + +`classmethod from_dimacs_file(filename)` + +Create a BooleanExpression from the string in the DIMACS format. :param filename: A file in DIMACS format. + +**Returns** + +A gate for the input string + +**Return type** + +[BooleanExpression](#qiskit.circuit.classicalfunction.BooleanExpression "qiskit.circuit.classicalfunction.BooleanExpression") + +**Raises** + +[**FileNotFoundError**](https://docs.python.org/3/library/exceptions.html#FileNotFoundError "(in Python v3.12)") – If filename is not found. + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### power + + + +`power(exponent)` + +Creates a unitary gate as gate^exponent. + +**Parameters** + +**exponent** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Gate^exponent + +**Returns** + +To which to\_matrix is self.to\_matrix^exponent. + +**Return type** + +.library.UnitaryGate + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If Gate is not unitary + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### simulate + + + +`simulate(bitstring)` + +Evaluate the expression on a bitstring. + +This evaluation is done classically. + +**Parameters** + +**bitstring** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The bitstring for which to evaluate. + +**Returns** + +result of the evaluation. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### synth + + + +`synth(registerless=True, synthesizer=None)` + +Synthesis the logic network into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +* **registerless** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Default `True`. If `False` uses the parameter names to create registers with those names. Otherwise, creates a circuit with a flat quantum register. +* **synthesizer** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*BooleanExpression*](#qiskit.circuit.classicalfunction.BooleanExpression "qiskit.circuit.classicalfunction.boolean_expression.BooleanExpression")*],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] | None*) – A callable that takes self and returns a Tweedledum circuit. + +**Returns** + +A circuit implementing the logic network. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### to\_matrix + + + +`to_matrix()` + +Return a Numpy.array for the gate unitary matrix. + +**Returns** + +if the Gate subclass has a matrix definition. + +**Return type** + +np.ndarray + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If a Gate subclass does not implement this method an exception will be raised when this base class method is called. + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Gate parameters should be int, float, or ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunction.md b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunction.md new file mode 100644 index 00000000000..44a8ab5b1a7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunction.md @@ -0,0 +1,544 @@ +--- +title: ClassicalFunction +description: API reference for qiskit.circuit.classicalfunction.ClassicalFunction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.classicalfunction.ClassicalFunction +--- + +# ClassicalFunction + + + +`qiskit.circuit.classicalfunction.ClassicalFunction(source, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classicalfunction/classicalfunction.py "view source code") + +Bases: `ClassicalElement` + +Represent a classical function and its logic network. + +Creates a `ClassicalFunction` from Python source code in `source`. + +The code should be a single function with types. + +**Parameters** + +* **source** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Python code with type hints. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. Default: “*classicalfunction*”. ClassicalFunction name. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If source is not a string. + +## Attributes + + + +### args + +Returns the classicalfunction arguments + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.classicalfunction.ClassicalFunction.base_class "qiskit.circuit.classicalfunction.ClassicalFunction.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### network + +Returns the logical network + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### qregs + +The list of qregs used by the classicalfunction + + + +### scopes + +Returns the scope dict + + + +### truth\_table + +Returns (and computes) the truth table + + + +### types + +Dumps a list of scopes with their variables and types. + +**Returns** + +A list of scopes as dicts, where key is the variable name and value is its type. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")([dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of quantum bit arguments. +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### compile + + + +`compile()` + +Parses and creates the logical circuit + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return controlled version of gate. See [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") for usage. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of controls to add to gate (default: `1`) +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – optional gate label +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The control state in decimal or as a bitstring (e.g. `'111'`). If `None`, use `2**num_ctrl_qubits-1`. + +**Returns** + +Controlled version of gate. This default algorithm uses `num_ctrl_qubits-1` ancilla qubits so returns a gate of size `num_qubits + 2*num_ctrl_qubits - 1`. + +**Return type** + +[qiskit.circuit.ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – unrecognized mode or invalid ctrl\_state + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### power + + + +`power(exponent)` + +Creates a unitary gate as gate^exponent. + +**Parameters** + +**exponent** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Gate^exponent + +**Returns** + +To which to\_matrix is self.to\_matrix^exponent. + +**Return type** + +.library.UnitaryGate + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If Gate is not unitary + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### simulate + + + +`simulate(bitstring)` + +Evaluate the expression on a bitstring. + +This evaluation is done classically. + +**Parameters** + +**bitstring** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The bitstring for which to evaluate. + +**Returns** + +result of the evaluation. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### simulate\_all + + + +`simulate_all()` + +Returns a truth table. + +**Returns** + +a bitstring with a truth table + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### synth + + + +`synth(registerless=True, synthesizer=None)` + +Synthesis the logic network into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Parameters** + +* **registerless** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Default `True`. If `False` uses the parameter names to create +* **Otherwise** (*registers with those names.*) – +* **register.** (*creates a circuit with a flat quantum*) – +* **synthesizer** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[ClassicalElement],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] | None*) – Optional. If None tweedledum’s pkrm\_synth is used. + +**Returns** + +A circuit implementing the logic network. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### to\_matrix + + + +`to_matrix()` + +Return a Numpy.array for the gate unitary matrix. + +**Returns** + +if the Gate subclass has a matrix definition. + +**Return type** + +np.ndarray + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If a Gate subclass does not implement this method an exception will be raised when this base class method is called. + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Gate parameters should be int, float, or ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md new file mode 100644 index 00000000000..94b9c516a35 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError.md @@ -0,0 +1,20 @@ +--- +title: ClassicalFunctionCompilerTypeError +description: API reference for qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError +in_page_toc_min_heading_level: 1 +python_api_type: exception +python_api_name: qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError +--- + + + +# qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError + + + +`qiskit.circuit.classicalfunction.ClassicalFunctionCompilerTypeError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classicalfunction/exceptions.py "view source code") + +ClassicalFunction compiler type error. The classicalfunction function fails at type checking time. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md new file mode 100644 index 00000000000..e9d783380b1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.classicalfunction.ClassicalFunctionParseError.md @@ -0,0 +1,20 @@ +--- +title: ClassicalFunctionParseError +description: API reference for qiskit.circuit.classicalfunction.ClassicalFunctionParseError +in_page_toc_min_heading_level: 1 +python_api_type: exception +python_api_name: qiskit.circuit.classicalfunction.ClassicalFunctionParseError +--- + + + +# qiskit.circuit.classicalfunction.ClassicalFunctionParseError + + + +`qiskit.circuit.classicalfunction.ClassicalFunctionParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/classicalfunction/exceptions.py "view source code") + +ClassicalFunction compiler parse error. The classicalfunction function fails at parsing time. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.AND.md b/docs/api/qiskit/0.46/qiskit.circuit.library.AND.md new file mode 100644 index 00000000000..612e6a9994f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.AND.md @@ -0,0 +1,227 @@ +--- +title: AND +description: API reference for qiskit.circuit.library.AND +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.AND +--- + +# AND + + + +`qiskit.circuit.library.AND(num_variable_qubits, flags=None, mcx_mode='noancilla')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/boolean_logic/quantum_and.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +A circuit implementing the logical AND operation on a number of qubits. + +For the AND operation the state $|1\rangle$ is interpreted as `True`. The result qubit is flipped, if the state of all variable qubits is `True`. In this format, the AND operation equals a multi-controlled X gate, which is controlled on all variable qubits. Using a list of flags however, qubits can be skipped or negated. Practically, the flags allow to skip controls or to apply pre- and post-X gates to the negated qubits. + +The AND gate without special flags equals the multi-controlled-X gate: + +![../\_images/qiskit-circuit-library-AND-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-AND-1.png) + +Using flags we can negate qubits or skip them. For instance, if we have 5 qubits and want to return `True` if the first qubit is `False` and the last two are `True` we use the flags `[-1, 0, 0, 1, 1]`. + +![../\_images/qiskit-circuit-library-AND-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-AND-2.png) + +Create a new logical AND circuit. + +**Parameters** + +* **num\_variable\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The qubits of which the OR is computed. The result will be written into an additional result qubit. +* **flags** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – A list of +1/0/-1 marking negations or omissions of qubits. +* **mcx\_mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The mode to be used to implement the multi-controlled X gate. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 193` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Barrier.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Barrier.md new file mode 100644 index 00000000000..dcc73097c35 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Barrier.md @@ -0,0 +1,311 @@ +--- +title: Barrier +description: API reference for qiskit.circuit.library.Barrier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Barrier +--- + +# Barrier + + + +`qiskit.circuit.library.Barrier(num_qubits, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/barrier.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Barrier instruction. + +A barrier is a visual indicator of the grouping of a circuit section. It also acts as a directive for circuit compilation to separate pieces of a circuit so that any optimizations or re-writes are constrained to only act between barriers. + +Create new barrier instruction. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits for the barrier type \[Default: 0]. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the barrier label + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – if barrier label is invalid. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.Barrier.base_class "qiskit.circuit.library.Barrier.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Special case. Return self. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.C3SXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.C3SXGate.md new file mode 100644 index 00000000000..4afb068188b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.C3SXGate.md @@ -0,0 +1,176 @@ +--- +title: C3SXGate +description: API reference for qiskit.circuit.library.C3SXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.C3SXGate +--- + +# C3SXGate + + + +`qiskit.circuit.library.C3SXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +The 3-qubit controlled sqrt-X gate. + +This implementation is based on Page 17 of \[1]. + +**References** + +\[1] Barenco et al., 1995. [https://arxiv.org/pdf/quant-ph/9503016.pdf](https://arxiv.org/pdf/quant-ph/9503016.pdf) + +Create a new 3-qubit controlled sqrt-X gate. + +**Parameters** + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.C3SXGate.base_class "qiskit.circuit.library.C3SXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### qasm + + + +`qasm()` + + + The method `qiskit.circuit.library.standard_gates.x.C3SXGate.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. + + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.C3XGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.C3XGate.md new file mode 100644 index 00000000000..b36568887b0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.C3XGate.md @@ -0,0 +1,187 @@ +--- +title: C3XGate +description: API reference for qiskit.circuit.library.C3XGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.C3XGate +--- + +# C3XGate + + + +`qiskit.circuit.library.C3XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +The X gate controlled on 3 qubits. + +This implementation uses $\sqrt{T}$ and 14 CNOT gates. + +Create a new 3-qubit controlled X gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.C3XGate.base_class "qiskit.circuit.library.C3XGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Controlled version of this gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Invert this gate. The C4X is its own inverse. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.C4XGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.C4XGate.md new file mode 100644 index 00000000000..6df286171a5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.C4XGate.md @@ -0,0 +1,191 @@ +--- +title: C4XGate +description: API reference for qiskit.circuit.library.C4XGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.C4XGate +--- + +# C4XGate + + + +`qiskit.circuit.library.C4XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +The 4-qubit controlled X gate. + +This implementation is based on Page 21, Lemma 7.5, of \[1], with the use of the relative phase version of c3x, the rc3x \[2]. + +**References** + +\[1] Barenco et al., 1995. [https://arxiv.org/pdf/quant-ph/9503016.pdf](https://arxiv.org/pdf/quant-ph/9503016.pdf) \[2] Maslov, 2015. [https://arxiv.org/abs/1508.03273](https://arxiv.org/abs/1508.03273) + +Create a new 4-qubit controlled X gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.C4XGate.base_class "qiskit.circuit.library.C4XGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Controlled version of this gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Invert this gate. The C4X is its own inverse. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CCXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CCXGate.md new file mode 100644 index 00000000000..0c6169baeae --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CCXGate.md @@ -0,0 +1,243 @@ +--- +title: CCXGate +description: API reference for qiskit.circuit.library.CCXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CCXGate +--- + +# CCXGate + + + +`qiskit.circuit.library.CCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +CCX gate, also known as Toffoli gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`ccx()`](qiskit.circuit.QuantumCircuit#ccx "qiskit.circuit.QuantumCircuit.ccx") and [`toffoli()`](qiskit.circuit.QuantumCircuit#toffoli "qiskit.circuit.QuantumCircuit.toffoli") methods. + +**Circuit symbol:** + +```python +q_0: ──■── + │ +q_1: ──■── + ┌─┴─┐ +q_2: ┤ X ├ + └───┘ +``` + +**Matrix representation:** + +$$ +CCX q_0, q_1, q_2 = + I \otimes I \otimes |0 \rangle \langle 0| + CX \otimes |1 \rangle \langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0\\ + 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0\\ + 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0\\ + 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1\\ + 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0\\ + 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0\\ + 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0\\ + 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_2 and q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───┐ + q_0: ┤ X ├ + └─┬─┘ + q_1: ──■── + │ + q_2: ──■── + ``` + + $$ + CCX\ q_2, q_1, q_0 = + |0 \rangle \langle 0| \otimes I \otimes I + |1 \rangle \langle 1| \otimes CX = + \begin{pmatrix} + 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0\\ + 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0\\ + 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0\\ + 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0\\ + 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0\\ + 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0\\ + 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1\\ + 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 + \end{pmatrix} + $$ + + +Create new CCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CCXGate.base_class "qiskit.circuit.library.CCXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Controlled version of this gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return an inverted CCX gate (also a CCX). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CCZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CCZGate.md new file mode 100644 index 00000000000..53fd3661a21 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CCZGate.md @@ -0,0 +1,196 @@ +--- +title: CCZGate +description: API reference for qiskit.circuit.library.CCZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CCZGate +--- + +# CCZGate + + + +`qiskit.circuit.library.CCZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/z.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +CCZ gate. + +This is a symmetric gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`ccz()`](qiskit.circuit.QuantumCircuit#ccz "qiskit.circuit.QuantumCircuit.ccz") method. + +**Circuit symbol:** + +```python +q_0: ─■─ + │ +q_1: ─■─ + │ +q_2: ─■─ +``` + +**Matrix representation:** + +$$ +CCZ\ q_0, q_1, q_2 = + I \otimes I \otimes |0\rangle\langle 0| + CZ \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 0 & 0 & -1 + \end{pmatrix} +$$ + +In the computational basis, this gate flips the phase of the target qubit if the control qubits are in the $|11\rangle$ state. + +Create new CCZ gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CCZGate.base_class "qiskit.circuit.library.CCZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted CCZ gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CDKMRippleCarryAdder.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CDKMRippleCarryAdder.md new file mode 100644 index 00000000000..d21cd10c0f7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CDKMRippleCarryAdder.md @@ -0,0 +1,283 @@ +--- +title: CDKMRippleCarryAdder +description: API reference for qiskit.circuit.library.CDKMRippleCarryAdder +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CDKMRippleCarryAdder +--- + +# CDKMRippleCarryAdder + + + +`qiskit.circuit.library.CDKMRippleCarryAdder(num_state_qubits, kind='full', name='CDKMRippleCarryAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/adders/cdkm_ripple_carry_adder.py "view source code") + +Bases: `Adder` + +A ripple-carry circuit to perform in-place addition on two qubit registers. + +As an example, a ripple-carry adder circuit that performs addition on two 3-qubit sized registers with a carry-in bit (`kind="full"`) is as follows: + +```python + ┌──────┐ ┌──────┐ + cin_0: ┤2 ├─────────────────────────────────────┤2 ├ + │ │┌──────┐ ┌──────┐│ │ + a_0: ┤0 ├┤2 ├─────────────────────┤2 ├┤0 ├ + │ ││ │┌──────┐ ┌──────┐│ ││ │ + a_1: ┤ MAJ ├┤0 ├┤2 ├─────┤2 ├┤0 ├┤ UMA ├ + │ ││ ││ │ │ ││ ││ │ + a_2: ┤ ├┤ MAJ ├┤0 ├──■──┤0 ├┤ UMA ├┤ ├ + │ ││ ││ │ │ │ ││ ││ │ + b_0: ┤1 ├┤ ├┤ MAJ ├──┼──┤ UMA ├┤ ├┤1 ├ + └──────┘│ ││ │ │ │ ││ │└──────┘ + b_1: ────────┤1 ├┤ ├──┼──┤ ├┤1 ├──────── + └──────┘│ │ │ │ │└──────┘ + b_2: ────────────────┤1 ├──┼──┤1 ├──────────────── + └──────┘┌─┴─┐└──────┘ +cout_0: ────────────────────────┤ X ├──────────────────────── + └───┘ +``` + +Here *MAJ* and *UMA* gates correspond to the gates introduced in \[1]. Note that in this implementation the input register qubits are ordered as all qubits from the first input register, followed by all qubits from the second input register. + +Two different kinds of adders are supported. By setting the `kind` argument, you can also choose a half-adder, which doesn’t have a carry-in, and a fixed-sized-adder, which has neither carry-in nor carry-out, and thus acts on fixed register sizes. Unlike the full-adder, these circuits need one additional helper qubit. + +The circuit diagram for the fixed-point adder (`kind="fixed"`) on 3-qubit sized inputs is + +```python + ┌──────┐┌──────┐ ┌──────┐┌──────┐ + a_0: ┤0 ├┤2 ├────────────────┤2 ├┤0 ├ + │ ││ │┌──────┐┌──────┐│ ││ │ + a_1: ┤ ├┤0 ├┤2 ├┤2 ├┤0 ├┤ ├ + │ ││ ││ ││ ││ ││ │ + a_2: ┤ ├┤ MAJ ├┤0 ├┤0 ├┤ UMA ├┤ ├ + │ ││ ││ ││ ││ ││ │ + b_0: ┤1 MAJ ├┤ ├┤ MAJ ├┤ UMA ├┤ ├┤1 UMA ├ + │ ││ ││ ││ ││ ││ │ + b_1: ┤ ├┤1 ├┤ ├┤ ├┤1 ├┤ ├ + │ │└──────┘│ ││ │└──────┘│ │ + b_2: ┤ ├────────┤1 ├┤1 ├────────┤ ├ + │ │ └──────┘└──────┘ │ │ +help_0: ┤2 ├────────────────────────────────┤2 ├ + └──────┘ └──────┘ +``` + +It has one less qubit than the full-adder since it doesn’t have the carry-out, but uses a helper qubit instead of the carry-in, so it only has one less qubit, not two. + +**References:** + +\[1] Cuccaro et al., A new quantum ripple-carry addition circuit, 2004. [arXiv:quant-ph/0410184](https://arxiv.org/pdf/quant-ph/0410184.pdf) + +\[2] Vedral et al., Quantum Networks for Elementary Arithmetic Operations, 1995. [arXiv:quant-ph/9511018](https://arxiv.org/pdf/quant-ph/9511018.pdf) + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits in either input register for state $|a\rangle$ or $|b\rangle$. The two input registers must have the same number of qubits. +* **kind** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The kind of adder, can be `'full'` for a full adder, `'half'` for a half adder, or `'fixed'` for a fixed-sized adder. A full adder includes both carry-in and carry-out, a half only carry-out, and a fixed-sized adder neither carry-in nor carry-out. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `num_state_qubits` is lower than 1. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits, i.e. the number of bits in each input register. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CHGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CHGate.md new file mode 100644 index 00000000000..8093f61659f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CHGate.md @@ -0,0 +1,211 @@ +--- +title: CHGate +description: API reference for qiskit.circuit.library.CHGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CHGate +--- + +# CHGate + + + +`qiskit.circuit.library.CHGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/h.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-Hadamard gate. + +Applies a Hadamard on the target qubit if the control is in the $|1\rangle$ state. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`ch()`](qiskit.circuit.QuantumCircuit#ch "qiskit.circuit.QuantumCircuit.ch") method. + +**Circuit symbol:** + +```python +q_0: ──■── + ┌─┴─┐ +q_1: ┤ H ├ + └───┘ +``` + +**Matrix Representation:** + +$$ +CH\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + H \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & \frac{1}{\sqrt{2}} & 0 & \frac{1}{\sqrt{2}} \\ + 0 & 0 & 1 & 0 \\ + 0 & \frac{1}{\sqrt{2}} & 0 & -\frac{1}{\sqrt{2}} + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───┐ + q_0: ┤ H ├ + └─┬─┘ + q_1: ──■── + ``` + + $$ + CH\ q_1, q_0 = + |0\rangle\langle 0| \otimes I + |1\rangle\langle 1| \otimes H = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & \frac{1}{\sqrt{2}} & \frac{1}{\sqrt{2}} \\ + 0 & 0 & \frac{1}{\sqrt{2}} & -\frac{1}{\sqrt{2}} + \end{pmatrix} + $$ + + +Create new CH gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CHGate.base_class "qiskit.circuit.library.CHGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted CH gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CPhaseGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CPhaseGate.md new file mode 100644 index 00000000000..caa15cce20f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CPhaseGate.md @@ -0,0 +1,222 @@ +--- +title: CPhaseGate +description: API reference for qiskit.circuit.library.CPhaseGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CPhaseGate +--- + +# CPhaseGate + + + +`qiskit.circuit.library.CPhaseGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/p.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-Phase gate. + +This is a diagonal and symmetric gate that induces a phase on the state of the target qubit, depending on the control state. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cp()`](qiskit.circuit.QuantumCircuit#cp "qiskit.circuit.QuantumCircuit.cp") method. + +**Circuit symbol:** + +```python +q_0: ─■── + │λ +q_1: ─■── +``` + +**Matrix representation:** + +$$ +CPhase = + I \otimes |0\rangle\langle 0| + P \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & e^{i\lambda} + \end{pmatrix} +$$ + + + `CRZGate`: Due to the global phase difference in the matrix definitions of Phase and RZ, CPhase and CRZ are different gates with a relative phase difference. + + +Create new CPhase gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CPhaseGate.base_class "qiskit.circuit.library.CPhaseGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Controlled version of this gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted CPhase gate ($CPhase(\lambda)^{\dagger} = CPhase(-\lambda)$) + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CRXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CRXGate.md new file mode 100644 index 00000000000..b9ebc221b24 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CRXGate.md @@ -0,0 +1,213 @@ +--- +title: CRXGate +description: API reference for qiskit.circuit.library.CRXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CRXGate +--- + +# CRXGate + + + +`qiskit.circuit.library.CRXGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rx.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-RX gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`crx()`](qiskit.circuit.QuantumCircuit#crx "qiskit.circuit.QuantumCircuit.crx") method. + +**Circuit symbol:** + +```python +q_0: ────■──── + ┌───┴───┐ +q_1: ┤ Rx(ϴ) ├ + └───────┘ +``` + +**Matrix representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +CRX(\theta)\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + RX(\theta) \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & \cos\left(\rotationangle\right) & 0 & -i\sin\left(\rotationangle\right) \\ + 0 & 0 & 1 & 0 \\ + 0 & -i\sin\left(\rotationangle\right) & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───────┐ + q_0: ┤ Rx(ϴ) ├ + └───┬───┘ + q_1: ────■──── + ``` + + $$ + \newcommand{\rotationangle}{\frac{\theta}{2}} + + CRX(\theta)\ q_1, q_0 = + |0\rangle\langle0| \otimes I + |1\rangle\langle1| \otimes RX(\theta) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) \\ + 0 & 0 & -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) + \end{pmatrix} + $$ + + +Create new CRX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CRXGate.base_class "qiskit.circuit.library.CRXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse CRX gate (i.e. with the negative rotation angle). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CRYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CRYGate.md new file mode 100644 index 00000000000..5e5413f5c56 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CRYGate.md @@ -0,0 +1,213 @@ +--- +title: CRYGate +description: API reference for qiskit.circuit.library.CRYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CRYGate +--- + +# CRYGate + + + +`qiskit.circuit.library.CRYGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/ry.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-RY gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cry()`](qiskit.circuit.QuantumCircuit#cry "qiskit.circuit.QuantumCircuit.cry") method. + +**Circuit symbol:** + +```python +q_0: ────■──── + ┌───┴───┐ +q_1: ┤ Ry(ϴ) ├ + └───────┘ +``` + +**Matrix representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +CRY(\theta)\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + RY(\theta) \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & \cos\left(\rotationangle\right) & 0 & -\sin\left(\rotationangle\right) \\ + 0 & 0 & 1 & 0 \\ + 0 & \sin\left(\rotationangle\right) & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───────┐ + q_0: ┤ Ry(ϴ) ├ + └───┬───┘ + q_1: ────■──── + ``` + + $$ + \newcommand{\rotationangle}{\frac{\theta}{2}} + + CRY(\theta)\ q_1, q_0 = + |0\rangle\langle 0| \otimes I + |1\rangle\langle 1| \otimes RY(\theta) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & \cos\left(\rotationangle\right) & -\sin\left(\rotationangle\right) \\ + 0 & 0 & \sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) + \end{pmatrix} + $$ + + +Create new CRY gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CRYGate.base_class "qiskit.circuit.library.CRYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse CRY gate (i.e. with the negative rotation angle). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CRZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CRZGate.md new file mode 100644 index 00000000000..3ecf0b95ed1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CRZGate.md @@ -0,0 +1,215 @@ +--- +title: CRZGate +description: API reference for qiskit.circuit.library.CRZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CRZGate +--- + +# CRZGate + + + +`qiskit.circuit.library.CRZGate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rz.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-RZ gate. + +This is a diagonal but non-symmetric gate that induces a phase on the state of the target qubit, depending on the control state. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`crz()`](qiskit.circuit.QuantumCircuit#crz "qiskit.circuit.QuantumCircuit.crz") method. + +**Circuit symbol:** + +```python +q_0: ────■──── + ┌───┴───┐ +q_1: ┤ Rz(λ) ├ + └───────┘ +``` + +**Matrix representation:** + +$$ +CRZ(\lambda)\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + RZ(\lambda) \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & e^{-i\frac{\lambda}{2}} & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & e^{i\frac{\lambda}{2}} + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───────┐ + q_0: ┤ Rz(λ) ├ + └───┬───┘ + q_1: ────■──── + ``` + + $$ + CRZ(\lambda)\ q_1, q_0 = + |0\rangle\langle 0| \otimes I + |1\rangle\langle 1| \otimes RZ(\lambda) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & e^{-i\frac{\lambda}{2}} & 0 \\ + 0 & 0 & 0 & e^{i\frac{\lambda}{2}} + \end{pmatrix} + $$ + + + + `CU1Gate`: Due to the global phase difference in the matrix definitions of U1 and RZ, CU1 and CRZ are different gates with a relative phase difference. + + +Create new CRZ gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CRZGate.base_class "qiskit.circuit.library.CRZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse CRZ gate (i.e. with the negative rotation angle). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CSGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CSGate.md new file mode 100644 index 00000000000..0d73e333043 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CSGate.md @@ -0,0 +1,195 @@ +--- +title: CSGate +description: API reference for qiskit.circuit.library.CSGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CSGate +--- + +# CSGate + + + +`qiskit.circuit.library.CSGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/s.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-S gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cs()`](qiskit.circuit.QuantumCircuit#cs "qiskit.circuit.QuantumCircuit.cs") method. + +**Circuit symbol:** + +```python +q_0: ──■── + ┌─┴─┐ +q_1: ┤ S ├ + └───┘ +``` + +**Matrix representation:** + +$$ +CS \ q_0, q_1 = +I \otimes |0 \rangle\langle 0| + S \otimes |1 \rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & i + \end{pmatrix} +$$ + +Create new CS gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CSGate.base_class "qiskit.circuit.library.CSGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse of CSGate (CSdgGate). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CSXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CSXGate.md new file mode 100644 index 00000000000..19647b1c8f3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CSXGate.md @@ -0,0 +1,199 @@ +--- +title: CSXGate +description: API reference for qiskit.circuit.library.CSXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CSXGate +--- + +# CSXGate + + + +`qiskit.circuit.library.CSXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/sx.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-√X gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`csx()`](qiskit.circuit.QuantumCircuit#csx "qiskit.circuit.QuantumCircuit.csx") method. + +**Circuit symbol:** + +```python +q_0: ──■── + ┌─┴──┐ +q_1: ┤ √X ├ + └────┘ +``` + +**Matrix representation:** + +$$ +C\sqrt{X} \ q_0, q_1 = +I \otimes |0 \rangle\langle 0| + \sqrt{X} \otimes |1 \rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & (1 + i) / 2 & 0 & (1 - i) / 2 \\ + 0 & 0 & 1 & 0 \\ + 0 & (1 - i) / 2 & 0 & (1 + i) / 2 + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌────┐ + q_0: ┤ √X ├ + └─┬──┘ + q_1: ──■── + ``` + + $$ + C\sqrt{X}\ q_1, q_0 = + |0 \rangle\langle 0| \otimes I + |1 \rangle\langle 1| \otimes \sqrt{X} = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & (1 + i) / 2 & (1 - i) / 2 \\ + 0 & 0 & (1 - i) / 2 & (1 + i) / 2 + \end{pmatrix} + $$ + + +Create new CSX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CSXGate.base_class "qiskit.circuit.library.CSXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CSdgGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CSdgGate.md new file mode 100644 index 00000000000..839c7f3565e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CSdgGate.md @@ -0,0 +1,195 @@ +--- +title: CSdgGate +description: API reference for qiskit.circuit.library.CSdgGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CSdgGate +--- + +# CSdgGate + + + +`qiskit.circuit.library.CSdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/s.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-S^dagger gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`csdg()`](qiskit.circuit.QuantumCircuit#csdg "qiskit.circuit.QuantumCircuit.csdg") method. + +**Circuit symbol:** + +```python +q_0: ───■─── + ┌──┴──┐ +q_1: ┤ Sdg ├ + └─────┘ +``` + +**Matrix representation:** + +$$ +CS^\dagger \ q_0, q_1 = +I \otimes |0 \rangle\langle 0| + S^\dagger \otimes |1 \rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & -i + \end{pmatrix} +$$ + +Create new CSdg gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CSdgGate.base_class "qiskit.circuit.library.CSdgGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse of CSdgGate (CSGate). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CSwapGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CSwapGate.md new file mode 100644 index 00000000000..344ad69c3f1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CSwapGate.md @@ -0,0 +1,230 @@ +--- +title: CSwapGate +description: API reference for qiskit.circuit.library.CSwapGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CSwapGate +--- + +# CSwapGate + + + +`qiskit.circuit.library.CSwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/swap.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-SWAP gate, also known as the Fredkin gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cswap()`](qiskit.circuit.QuantumCircuit#cswap "qiskit.circuit.QuantumCircuit.cswap") and [`fredkin()`](qiskit.circuit.QuantumCircuit#fredkin "qiskit.circuit.QuantumCircuit.fredkin") methods. + +**Circuit symbol:** + +```python +q_0: ─■─ + │ +q_1: ─X─ + │ +q_2: ─X─ +``` + +**Matrix representation:** + +$$ +CSWAP\ q_0, q_1, q_2 = + I \otimes I \otimes |0 \rangle \langle 0| + + SWAP \otimes |1 \rangle \langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\ + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_2. Thus a textbook matrix for this gate will be: + + ```python + q_0: ─X─ + │ + q_1: ─X─ + │ + q_2: ─■─ + ``` + + $$ + CSWAP\ q_2, q_1, q_0 = + |0 \rangle \langle 0| \otimes I \otimes I + + |1 \rangle \langle 1| \otimes SWAP = + \begin{pmatrix} + 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\ + \end{pmatrix} + $$ + + +In the computational basis, this gate swaps the states of the two target qubits if the control qubit is in the $|1\rangle$ state. + +$$ +|0, b, c\rangle \rightarrow |0, b, c\rangle +|1, b, c\rangle \rightarrow |1, c, b\rangle + + +$$ + +Create new CSWAP gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CSwapGate.base_class "qiskit.circuit.library.CSwapGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse CSwap gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CU1Gate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CU1Gate.md new file mode 100644 index 00000000000..589b7e5fe13 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CU1Gate.md @@ -0,0 +1,212 @@ +--- +title: CU1Gate +description: API reference for qiskit.circuit.library.CU1Gate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CU1Gate +--- + +# CU1Gate + + + +`qiskit.circuit.library.CU1Gate(theta, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u1.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-U1 gate. + +This is a diagonal and symmetric gate that induces a phase on the state of the target qubit, depending on the control state. + +**Circuit symbol:** + +```python +q_0: ─■── + │λ +q_1: ─■── +``` + +**Matrix representation:** + +$$ +CU1(\lambda) = + I \otimes |0\rangle\langle 0| + U1 \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & e^{i\lambda} + \end{pmatrix} +$$ + + + `CRZGate`: Due to the global phase difference in the matrix definitions of U1 and RZ, CU1 and CRZ are different gates with a relative phase difference. + + +Create new CU1 gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CU1Gate.base_class "qiskit.circuit.library.CU1Gate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Controlled version of this gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted CU1 gate ($CU1(\lambda)^{\dagger} = CU1(-\lambda)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CU3Gate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CU3Gate.md new file mode 100644 index 00000000000..1e97d6be50e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CU3Gate.md @@ -0,0 +1,217 @@ +--- +title: CU3Gate +description: API reference for qiskit.circuit.library.CU3Gate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CU3Gate +--- + +# CU3Gate + + + +`qiskit.circuit.library.CU3Gate(theta, phi, lam, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u3.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-U3 gate (3-parameter two-qubit gate). + +This is a controlled version of the U3 gate (generic single qubit rotation). It is restricted to 3 parameters, and so cannot cover generic two-qubit controlled gates). + +**Circuit symbol:** + +```python +q_0: ──────■────── + ┌─────┴─────┐ +q_1: ┤ U3(ϴ,φ,λ) ├ + └───────────┘ +``` + +**Matrix representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +CU3(\theta, \phi, \lambda)\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + + U3(\theta,\phi,\lambda) \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & \cos(\rotationangle) & 0 & -e^{i\lambda}\sin(\rotationangle) \\ + 0 & 0 & 1 & 0 \\ + 0 & e^{i\phi}\sin(\rotationangle) & 0 & e^{i(\phi+\lambda)}\cos(\rotationangle) + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───────────┐ + q_0: ┤ U3(ϴ,φ,λ) ├ + └─────┬─────┘ + q_1: ──────■────── + ``` + + $$ + \newcommand{\rotationangle}{\frac{\theta}{2}} + + CU3(\theta, \phi, \lambda)\ q_1, q_0 = + |0\rangle\langle 0| \otimes I + + |1\rangle\langle 1| \otimes U3(\theta,\phi,\lambda) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & \cos(\rotationangle) & -e^{i\lambda}\sin(\rotationangle) \\ + 0 & 0 & e^{i\phi}\sin(\rotationangle) & e^{i(\phi+\lambda)}\cos(\rotationangle) + \end{pmatrix} + $$ + + +Create new CU3 gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CU3Gate.base_class "qiskit.circuit.library.CU3Gate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted CU3 gate. + +$CU3(\theta,\phi,\lambda)^{\dagger} =CU3(-\theta,-\phi,-\lambda)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CUGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CUGate.md new file mode 100644 index 00000000000..dc2e6b48a14 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CUGate.md @@ -0,0 +1,207 @@ +--- +title: CUGate +description: API reference for qiskit.circuit.library.CUGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CUGate +--- + +# CUGate + + + +`qiskit.circuit.library.CUGate(theta, phi, lam, gamma, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Controlled-U gate (4-parameter two-qubit gate). + +This is a controlled version of the U gate (generic single qubit rotation), including a possible global phase $e^{i\gamma}$ of the U gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cu()`](qiskit.circuit.QuantumCircuit#cu "qiskit.circuit.QuantumCircuit.cu") method. + +**Circuit symbol:** + +```python +q_0: ──────■────── + ┌─────┴──────┐ +q_1: ┤ U(ϴ,φ,λ,γ) ├ + └────────────┘ +``` + +**Matrix representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +CU(\theta, \phi, \lambda, \gamma)\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + + e^{i\gamma} U(\theta,\phi,\lambda) \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & e^{i\gamma}\cos(\rotationangle) & + 0 & -e^{i(\gamma + \lambda)}\sin(\rotationangle) \\ + 0 & 0 & 1 & 0 \\ + 0 & e^{i(\gamma+\phi)}\sin(\rotationangle) & + 0 & e^{i(\gamma+\phi+\lambda)}\cos(\rotationangle) + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌────────────┐ + q_0: ┤ U(ϴ,φ,λ,γ) ├ + └─────┬──────┘ + q_1: ──────■─────── + ``` + + $$ + \newcommand{\rotationangle}{\frac{\theta}{2}} + CU(\theta, \phi, \lambda, \gamma)\ q_1, q_0 = + |0\rangle\langle 0| \otimes I + + e^{i\gamma}|1\rangle\langle 1| \otimes U(\theta,\phi,\lambda) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & e^{i\gamma} \cos(\rotationangle) & -e^{i(\gamma + \lambda)}\sin(\rotationangle) \\ + 0 & 0 & + e^{i(\gamma + \phi)}\sin(\rotationangle) & e^{i(\gamma + \phi+\lambda)}\cos(\rotationangle) + \end{pmatrix} + $$ + + +Create new CU gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CUGate.base_class "qiskit.circuit.library.CUGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted CU gate. + +$CU(\theta,\phi,\lambda,\gamma)^{\dagger} = CU(-\theta,-\phi,-\lambda,-\gamma)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CXGate.md new file mode 100644 index 00000000000..9aac3159491 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CXGate.md @@ -0,0 +1,239 @@ +--- +title: CXGate +description: API reference for qiskit.circuit.library.CXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CXGate +--- + +# CXGate + + + +`qiskit.circuit.library.CXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-X gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cx()`](qiskit.circuit.QuantumCircuit#cx "qiskit.circuit.QuantumCircuit.cx") and [`cnot()`](qiskit.circuit.QuantumCircuit#cnot "qiskit.circuit.QuantumCircuit.cnot") methods. + +**Circuit symbol:** + +```python +q_0: ──■── + ┌─┴─┐ +q_1: ┤ X ├ + └───┘ +``` + +**Matrix representation:** + +$$ +CX\ q_0, q_1 = + I \otimes |0\rangle\langle0| + X \otimes |1\rangle\langle1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 1 \\ + 0 & 0 & 1 & 0 \\ + 0 & 1 & 0 & 0 + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───┐ + q_0: ┤ X ├ + └─┬─┘ + q_1: ──■── + ``` + + $$ + CX\ q_1, q_0 = + |0 \rangle\langle 0| \otimes I + |1 \rangle\langle 1| \otimes X = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & 1 \\ + 0 & 0 & 1 & 0 + \end{pmatrix} + $$ + + +In the computational basis, this gate flips the target qubit if the control qubit is in the $|1\rangle$ state. In this sense it is similar to a classical XOR gate. + +$$ +`|a, b\rangle \rightarrow |a, a \oplus b\rangle` + + +$$ + +Create new CX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CXGate.base_class "qiskit.circuit.library.CXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a controlled-X gate with more control lines. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted CX gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CYGate.md new file mode 100644 index 00000000000..99228a9d25c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CYGate.md @@ -0,0 +1,209 @@ +--- +title: CYGate +description: API reference for qiskit.circuit.library.CYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CYGate +--- + +# CYGate + + + +`qiskit.circuit.library.CYGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/y.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-Y gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cy()`](qiskit.circuit.QuantumCircuit#cy "qiskit.circuit.QuantumCircuit.cy") method. + +**Circuit symbol:** + +```python +q_0: ──■── + ┌─┴─┐ +q_1: ┤ Y ├ + └───┘ +``` + +**Matrix representation:** + +$$ +CY\ q_0, q_1 = +I \otimes |0 \rangle\langle 0| + Y \otimes |1 \rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 0 & 0 & -i \\ + 0 & 0 & 1 & 0 \\ + 0 & i & 0 & 0 + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In many textbooks, controlled gates are presented with the assumption of more significant qubits as control, which in our case would be q\_1. Thus a textbook matrix for this gate will be: + + ```python + ┌───┐ + q_0: ┤ Y ├ + └─┬─┘ + q_1: ──■── + ``` + + $$ + CY\ q_1, q_0 = + |0 \rangle\langle 0| \otimes I + |1 \rangle\langle 1| \otimes Y = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & -i \\ + 0 & 0 & i & 0 + \end{pmatrix} + $$ + + +Create new CY gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CYGate.base_class "qiskit.circuit.library.CYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted CY gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.CZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.CZGate.md new file mode 100644 index 00000000000..01d2b7e0f3e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.CZGate.md @@ -0,0 +1,190 @@ +--- +title: CZGate +description: API reference for qiskit.circuit.library.CZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.CZGate +--- + +# CZGate + + + +`qiskit.circuit.library.CZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/z.py "view source code") + +Bases: [`SingletonControlledGate`](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +Controlled-Z gate. + +This is a Clifford and symmetric gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`cz()`](qiskit.circuit.QuantumCircuit#cz "qiskit.circuit.QuantumCircuit.cz") method. + +**Circuit symbol:** + +```python +q_0: ─■─ + │ +q_1: ─■─ +``` + +**Matrix representation:** + +$$ +CZ\ q_0, q_1 = + I \otimes |0\rangle\langle 0| + Z \otimes |1\rangle\langle 1| = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & -1 + \end{pmatrix} +$$ + +In the computational basis, this gate flips the phase of the target qubit if the control qubit is in the $|1\rangle$ state. + +Create new CZ gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.CZGate.base_class "qiskit.circuit.library.CZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted CZ gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.DCXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.DCXGate.md new file mode 100644 index 00000000000..c2e34acbfd6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.DCXGate.md @@ -0,0 +1,141 @@ +--- +title: DCXGate +description: API reference for qiskit.circuit.library.DCXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.DCXGate +--- + +# DCXGate + + + +`qiskit.circuit.library.DCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/dcx.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Double-CNOT gate. + +A 2-qubit Clifford gate consisting of two back-to-back CNOTs with alternate controls. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`dcx()`](qiskit.circuit.QuantumCircuit#dcx "qiskit.circuit.QuantumCircuit.dcx") method. + +```python + ┌───┐ +q_0: ──■──┤ X ├ + ┌─┴─┐└─┬─┘ +q_1: ┤ X ├──■── + └───┘ +``` + +This is a classical logic gate, equivalent to a CNOT-SWAP (CNS) sequence, and locally equivalent to an iSWAP. + +$$ +DCX\ q_0, q_1 = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 0 & 0 & 1 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 + \end{pmatrix} +$$ + +Create new DCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.DCXGate.base_class "qiskit.circuit.library.DCXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Diagonal.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Diagonal.md new file mode 100644 index 00000000000..2d0660b1c8b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Diagonal.md @@ -0,0 +1,255 @@ +--- +title: Diagonal +description: API reference for qiskit.circuit.library.Diagonal +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Diagonal +--- + +# Diagonal + + + +`qiskit.circuit.library.Diagonal(diag)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/diagonal.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Diagonal circuit. + +Circuit symbol: + +```python + ┌───────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 Diagonal ├ + │ │ +q_2: ┤2 ├ + └───────────┘ +``` + +Matrix form: + +$$ +\text{DiagonalGate}\ q_0, q_1, .., q_{n-1} = + \begin{pmatrix} + D[0] & 0 & \dots & 0 \\ + 0 & D[1] & \dots & 0 \\ + \vdots & \vdots & \ddots & 0 \\ + 0 & 0 & \dots & D[n-1] + \end{pmatrix} + + +$$ + +Diagonal gates are useful as representations of Boolean functions, as they can map from $\{0,1\}^{2^n}$ to $\{0,1\}^{2^n}$ space. For example a phase oracle can be seen as a diagonal gate with $\{1, -1\}$ on the diagonals. Such an oracle will induce a $+1$ or :math\`-1\` phase on the amplitude of any corresponding basis state. + +Diagonal gates appear in many classically hard oracular problems such as Forrelation or Hidden Shift circuits. + +Diagonal gates are represented and simulated more efficiently than a dense $2^n \times 2^n$ unitary matrix. + +The reference implementation is via the method described in Theorem 7 of \[1]. The code is based on Emanuel Malvetti’s semester thesis at ETH in 2018, supervised by Raban Iten and Prof. Renato Renner. + +**Reference:** + +\[1] Shende et al., Synthesis of Quantum Logic Circuits, 2009 [arXiv:0406176](https://arxiv.org/pdf/quant-ph/0406176.pdf) + +**Parameters** + +**diag** (*Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]*) – List of the $2^k$ diagonal entries (for a diagonal gate on $k$ qubits). + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the list of the diagonal entries or the qubit list is in bad format; if the number of diagonal entries is not $2^k$, where $k$ denotes the number of qubits. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.DiagonalGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.DiagonalGate.md new file mode 100644 index 00000000000..33fd6d7b987 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.DiagonalGate.md @@ -0,0 +1,137 @@ +--- +title: DiagonalGate +description: API reference for qiskit.circuit.library.DiagonalGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.DiagonalGate +--- + +# DiagonalGate + + + +`qiskit.circuit.library.DiagonalGate(diag)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/diagonal.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Gate implementing a diagonal transformation. + +**Parameters** + +**diag** (*Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]*) – list of the $2^k$ diagonal entries (for a diagonal gate on $k$ qubits). + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.DiagonalGate.base_class "qiskit.circuit.library.DiagonalGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return the inverse of the diagonal gate. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Diagonal Gate parameter should accept complex (in addition to the Gate parameter types) and always return build-in complex. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.DraperQFTAdder.md b/docs/api/qiskit/0.46/qiskit.circuit.library.DraperQFTAdder.md new file mode 100644 index 00000000000..1075c4a53a2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.DraperQFTAdder.md @@ -0,0 +1,254 @@ +--- +title: DraperQFTAdder +description: API reference for qiskit.circuit.library.DraperQFTAdder +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.DraperQFTAdder +--- + +# DraperQFTAdder + + + +`qiskit.circuit.library.DraperQFTAdder(num_state_qubits, kind='fixed', name='DraperQFTAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/adders/draper_qft_adder.py "view source code") + +Bases: `Adder` + +A circuit that uses QFT to perform in-place addition on two qubit registers. + +For registers with $n$ qubits, the QFT adder can perform addition modulo $2^n$ (with `kind="fixed"`) or ordinary addition by adding a carry qubits (with `kind="half"`). + +As an example, a non-fixed\_point QFT adder circuit that performs addition on two 2-qubit sized registers is as follows: + +```python + a_0: ─────────■──────■────────────────────────■──────────────── + │ │ │ + a_1: ─────────┼──────┼────────■──────■────────┼──────────────── + ┌──────┐ │P(π) │ │ │ │ ┌───────┐ + b_0: ┤0 ├─■──────┼────────┼──────┼────────┼───────┤0 ├ + │ │ │P(π/2) │P(π) │ │ │ │ + b_1: ┤1 qft ├────────■────────■──────┼────────┼───────┤1 iqft ├ + │ │ │P(π/2) │P(π/4) │ │ +cout_0: ┤2 ├────────────────────────■────────■───────┤2 ├ + └──────┘ └───────┘ +``` + +**References:** + +\[1] T. G. Draper, Addition on a Quantum Computer, 2000. [arXiv:quant-ph/0008033](https://arxiv.org/pdf/quant-ph/0008033.pdf) + +\[2] Ruiz-Perez et al., Quantum arithmetic with the Quantum Fourier Transform, 2017. [arXiv:1411.5949](https://arxiv.org/pdf/1411.5949.pdf) + +\[3] Vedral et al., Quantum Networks for Elementary Arithmetic Operations, 1995. [arXiv:quant-ph/9511018](https://arxiv.org/pdf/quant-ph/9511018.pdf) + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits in either input register for state $|a\rangle$ or $|b\rangle$. The two input registers must have the same number of qubits. +* **kind** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The kind of adder, can be `'half'` for a half adder or `'fixed'` for a fixed-sized adder. A half adder contains a carry-out to represent the most-significant bit, but the fixed-sized adder doesn’t and hence performs addition modulo `2 ** num_state_qubits`. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `num_state_qubits` is lower than 1. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits, i.e. the number of bits in each input register. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.ECRGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.ECRGate.md new file mode 100644 index 00000000000..6338fdb1fe9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.ECRGate.md @@ -0,0 +1,175 @@ +--- +title: ECRGate +description: API reference for qiskit.circuit.library.ECRGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.ECRGate +--- + +# ECRGate + + + +`qiskit.circuit.library.ECRGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/ecr.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +An echoed cross-resonance gate. + +This gate is maximally entangling and is equivalent to a CNOT up to single-qubit pre-rotations. The echoing procedure mitigates some unwanted terms (terms other than ZX) to cancel in an experiment. More specifically, this gate implements $\frac{1}{\sqrt{2}}(IX-XY)$. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`ecr()`](qiskit.circuit.QuantumCircuit#ecr "qiskit.circuit.QuantumCircuit.ecr") method. + +**Circuit Symbol:** + +```python + ┌─────────┐ ┌────────────┐┌────────┐┌─────────────┐ +q_0: ┤0 ├ q_0: ┤0 ├┤ RX(pi) ├┤0 ├ + │ ECR │ = │ RZX(pi/4) │└────────┘│ RZX(-pi/4) │ +q_1: ┤1 ├ q_1: ┤1 ├──────────┤1 ├ + └─────────┘ └────────────┘ └─────────────┘ +``` + +**Matrix Representation:** + +$$ +ECR\ q_0, q_1 = \frac{1}{\sqrt{2}} + \begin{pmatrix} + 0 & 1 & 0 & i \\ + 1 & 0 & -i & 0 \\ + 0 & i & 0 & 1 \\ + -i & 0 & 1 & 0 + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In the above example we apply the gate on (q\_0, q\_1) which results in the $X \otimes Z$ tensor order. Instead, if we apply it on (q\_1, q\_0), the matrix will be $Z \otimes X$: + + ```python + ┌─────────┐ + q_0: ┤1 ├ + │ ECR │ + q_1: ┤0 ├ + └─────────┘ + ``` + + $$ + ECR\ q_0, q_1 = \frac{1}{\sqrt{2}} + \begin{pmatrix} + 0 & 0 & 1 & i \\ + 0 & 0 & i & 1 \\ + 1 & -i & 0 & 0 \\ + -i & 1 & 0 & 0 + \end{pmatrix} + $$ + + +Create new ECR gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.ECRGate.base_class "qiskit.circuit.library.ECRGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse ECR gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.EfficientSU2.md b/docs/api/qiskit/0.46/qiskit.circuit.library.EfficientSU2.md new file mode 100644 index 00000000000..a510dad5833 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.EfficientSU2.md @@ -0,0 +1,351 @@ +--- +title: EfficientSU2 +description: API reference for qiskit.circuit.library.EfficientSU2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.EfficientSU2 +--- + +# EfficientSU2 + + + +`qiskit.circuit.library.EfficientSU2(num_qubits=None, su2_gates=None, entanglement='reverse_linear', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='EfficientSU2', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/efficient_su2.py "view source code") + +Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") + +The hardware efficient SU(2) 2-local circuit. + +The `EfficientSU2` circuit consists of layers of single qubit operations spanned by SU(2) and $CX$ entanglements. This is a heuristic pattern that can be used to prepare trial wave functions for variational quantum algorithms or classification circuit for machine learning. + +SU(2) stands for special unitary group of degree 2, its elements are $2 \times 2$ unitary matrices with determinant 1, such as the Pauli rotation gates. + +On 3 qubits and using the Pauli $Y$ and $Z$ su2\_gates as single qubit gates, the hardware efficient SU(2) circuit is represented by: + +```python +┌──────────┐┌──────────┐ ░ ░ ░ ┌───────────┐┌───────────┐ +┤ RY(θ[0]) ├┤ RZ(θ[3]) ├─░────────■───░─ ... ─░─┤ RY(θ[12]) ├┤ RZ(θ[15]) ├ +├──────────┤├──────────┤ ░ ┌─┴─┐ ░ ░ ├───────────┤├───────────┤ +┤ RY(θ[1]) ├┤ RZ(θ[4]) ├─░───■──┤ X ├─░─ ... ─░─┤ RY(θ[13]) ├┤ RZ(θ[16]) ├ +├──────────┤├──────────┤ ░ ┌─┴─┐└───┘ ░ ░ ├───────────┤├───────────┤ +┤ RY(θ[2]) ├┤ RZ(θ[5]) ├─░─┤ X ├──────░─ ... ─░─┤ RY(θ[14]) ├┤ RZ(θ[17]) ├ +└──────────┘└──────────┘ ░ └───┘ ░ ░ └───────────┘└───────────┘ +``` + +See [`RealAmplitudes`](qiskit.circuit.library.RealAmplitudes "qiskit.circuit.library.RealAmplitudes") for more detail on the possible arguments and options such as skipping unentanglement qubits, which apply here too. + +**Examples** + +```python +>>> circuit = EfficientSU2(3, reps=1) +>>> print(circuit) + ┌──────────┐┌──────────┐ ┌──────────┐┌──────────┐ +q_0: ┤ RY(θ[0]) ├┤ RZ(θ[3]) ├──■────■──┤ RY(θ[6]) ├┤ RZ(θ[9]) ├───────────── + ├──────────┤├──────────┤┌─┴─┐ │ └──────────┘├──────────┤┌───────────┐ +q_1: ┤ RY(θ[1]) ├┤ RZ(θ[4]) ├┤ X ├──┼───────■──────┤ RY(θ[7]) ├┤ RZ(θ[10]) ├ + ├──────────┤├──────────┤└───┘┌─┴─┐ ┌─┴─┐ ├──────────┤├───────────┤ +q_2: ┤ RY(θ[2]) ├┤ RZ(θ[5]) ├─────┤ X ├───┤ X ├────┤ RY(θ[8]) ├┤ RZ(θ[11]) ├ + └──────────┘└──────────┘ └───┘ └───┘ └──────────┘└───────────┘ +``` + +```python +>>> ansatz = EfficientSU2(4, su2_gates=['rx', 'y'], entanglement='circular', reps=1) +>>> qc = QuantumCircuit(4) # create a circuit and append the RY variational form +>>> qc.compose(ansatz, inplace=True) +>>> qc.draw() + ┌──────────┐┌───┐┌───┐ ┌──────────┐ ┌───┐ +q_0: ┤ RX(θ[0]) ├┤ Y ├┤ X ├──■──┤ RX(θ[4]) ├───┤ Y ├───────────────────── + ├──────────┤├───┤└─┬─┘┌─┴─┐└──────────┘┌──┴───┴───┐ ┌───┐ +q_1: ┤ RX(θ[1]) ├┤ Y ├──┼──┤ X ├─────■──────┤ RX(θ[5]) ├───┤ Y ├───────── + ├──────────┤├───┤ │ └───┘ ┌─┴─┐ └──────────┘┌──┴───┴───┐┌───┐ +q_2: ┤ RX(θ[2]) ├┤ Y ├──┼──────────┤ X ├─────────■──────┤ RX(θ[6]) ├┤ Y ├ + ├──────────┤├───┤ │ └───┘ ┌─┴─┐ ├──────────┤├───┤ +q_3: ┤ RX(θ[3]) ├┤ Y ├──■──────────────────────┤ X ├────┤ RX(θ[7]) ├┤ Y ├ + └──────────┘└───┘ └───┘ └──────────┘└───┘ +``` + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits of the EfficientSU2 circuit. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Specifies how often the structure of a rotation layer followed by an entanglement layer is repeated. +* **su2\_gates** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – The SU(2) single qubit gates to apply in single qubit gate layers. If only one gate is provided, the same gate is applied to each qubit. If a list of gates is provided, all gates are applied to each qubit in the provided order. +* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Specifies the entanglement structure. Can be a string (‘full’, ‘linear’ , ‘reverse\_linear’, ‘circular’ or ‘sca’), a list of integer-pairs specifying the indices of qubits entangled with one another, or a callable returning such a list provided with the index of the entanglement layer. Default to ‘reverse\_linear’ entanglement. Note that ‘reverse\_linear’ entanglement provides the same unitary as ‘full’ with fewer entangling gates. See the Examples section of [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.TwoLocal") for more detail. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A QuantumCircuit object to prepend to the circuit. +* **skip\_unentangled\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, the single qubit gates are only applied to qubits that are entangled with another qubit. If False, the single qubit gates are applied to each qubit in the Ansatz. Defaults to False. +* **skip\_final\_rotation\_layer** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If False, a rotation layer is added at the end of the ansatz. If True, no rotation layer is added. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The parameterized gates require a parameter to be defined, for which we use [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector"). +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted in between each layer. If False, no barriers are inserted. +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +Return the parameter bounds. + +**Returns** + +The parameter bounds. + + + +### parameters + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.EvolvedOperatorAnsatz.md b/docs/api/qiskit/0.46/qiskit.circuit.library.EvolvedOperatorAnsatz.md new file mode 100644 index 00000000000..a689c6d8fe3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.EvolvedOperatorAnsatz.md @@ -0,0 +1,319 @@ +--- +title: EvolvedOperatorAnsatz +description: API reference for qiskit.circuit.library.EvolvedOperatorAnsatz +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.EvolvedOperatorAnsatz +--- + +# EvolvedOperatorAnsatz + + + +`qiskit.circuit.library.EvolvedOperatorAnsatz(operators=None, reps=1, evolution=None, insert_barriers=False, name='EvolvedOps', parameter_prefix='t', initial_state=None, flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/evolved_operator_ansatz.py "view source code") + +Bases: [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.n_local.n_local.NLocal") + +The evolved operator ansatz. + +**Parameters** + +* **operators** (*BaseOperator |* [*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *| None*) – The operators to evolve. If a circuit is passed, we assume it implements an already evolved operator and thus the circuit is not evolved again. Can be a single operator (circuit) or a list of operators (and circuits). +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to repeat the evolved operators. +* **evolution** ([*EvolutionBase*](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.EvolutionBase") *|*[*EvolutionSynthesis*](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis") *| None*) – A specification of which evolution synthesis to use for the [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate"), if the operator is from [`qiskit.quantum_info`](quantum_info#module-qiskit.quantum_info "qiskit.quantum_info") or an opflow converter object if the operator is from [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow"). Defaults to first order Trotterization. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to insert barriers in between each evolution. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| Sequence\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Set the names of the circuit parameters. If a string, the same prefix will be used for each parameters. Can also be a list to specify a prefix per operator. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object to prepend to the circuit. +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### evolution + +The evolution converter used to compute the evolution. + +**Returns** + +The evolution converter used to compute the evolution. + +**Return type** + +[EvolutionBase](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.EvolutionBase") or [EvolutionSynthesis](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis") + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### operators + +The operators that are evolved in this circuit. + +**Returns** + +The operators to be evolved (and circuits) contained in this ansatz. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### preferred\_init\_points + +Getter of preferred initial points based on the given initial state. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.ExactReciprocal.md b/docs/api/qiskit/0.46/qiskit.circuit.library.ExactReciprocal.md new file mode 100644 index 00000000000..f21867e703e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.ExactReciprocal.md @@ -0,0 +1,224 @@ +--- +title: ExactReciprocal +description: API reference for qiskit.circuit.library.ExactReciprocal +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.ExactReciprocal +--- + +# ExactReciprocal + + + +`qiskit.circuit.library.ExactReciprocal(num_state_qubits, scaling, neg_vals=False, name='1/x')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/exact_reciprocal.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Exact reciprocal + +$$ +|x\rangle |0\rangle \mapsto \cos(1/x)|x\rangle|0\rangle + \sin(1/x)|x\rangle |1\rangle +$$ + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits representing the value to invert. +* **scaling** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Scaling factor $s$ of the reciprocal function, i.e. to compute $s / x$. +* **neg\_vals** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether $x$ might represent negative values. In this case the first qubit is the sign, with $|1\rangle$ for negative and $|0\rangle$ for positive. For the negative case it is assumed that the remaining string represents $1 - x$. This is because $e^{-2 \pi i x} = e^{2 \pi i (1 - x)}$ for $x \in [0,1)$. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the object. + + + It is assumed that the binary string $x$ represents a number \< 1. + + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.ExcitationPreserving.md b/docs/api/qiskit/0.46/qiskit.circuit.library.ExcitationPreserving.md new file mode 100644 index 00000000000..c753ee5bd58 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.ExcitationPreserving.md @@ -0,0 +1,370 @@ +--- +title: ExcitationPreserving +description: API reference for qiskit.circuit.library.ExcitationPreserving +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.ExcitationPreserving +--- + +# ExcitationPreserving + + + +`qiskit.circuit.library.ExcitationPreserving(num_qubits=None, mode='iswap', entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='ExcitationPreserving', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/excitation_preserving.py "view source code") + +Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") + +The heuristic excitation-preserving wave function ansatz. + +The `ExcitationPreserving` circuit preserves the ratio of $|00\rangle$, $|01\rangle + |10\rangle$ and $|11\rangle$ states. To this end, this circuit uses two-qubit interactions of the form + +$$ +\newcommand{\rotationangle}{\theta/2} + +\begin{pmatrix} +1 & 0 & 0 & 0 \\ +0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) & 0 \\ +0 & -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) & 0 \\ +0 & 0 & 0 & e^{-i\phi} +\end{pmatrix} +$$ + +for the mode `'fsim'` or with $e^{-i\phi} = 1$ for the mode `'iswap'`. + +Note that other wave functions, such as UCC-ansatzes, are also excitation preserving. However these can become complex quickly, while this heuristically motivated circuit follows a simpler pattern. + +This trial wave function consists of layers of $Z$ rotations with 2-qubit entanglements. The entangling is creating using $XX+YY$ rotations and optionally a controlled-phase gate for the mode `'fsim'`. + +See [`RealAmplitudes`](qiskit.circuit.library.RealAmplitudes "qiskit.circuit.library.RealAmplitudes") for more detail on the possible arguments and options such as skipping unentanglement qubits, which apply here too. + +The rotations of the ExcitationPreserving ansatz can be written as + +**Examples** + +```python +>>> ansatz = ExcitationPreserving(3, reps=1, insert_barriers=True, entanglement='linear') +>>> print(ansatz) # show the circuit + ┌──────────┐ ░ ┌────────────┐┌────────────┐ ░ ┌──────────┐ +q_0: ┤ RZ(θ[0]) ├─░─┤0 ├┤0 ├─────────────────────────────░─┤ RZ(θ[5]) ├ + ├──────────┤ ░ │ RXX(θ[3]) ││ RYY(θ[3]) │┌────────────┐┌────────────┐ ░ ├──────────┤ +q_1: ┤ RZ(θ[1]) ├─░─┤1 ├┤1 ├┤0 ├┤0 ├─░─┤ RZ(θ[6]) ├ + ├──────────┤ ░ └────────────┘└────────────┘│ RXX(θ[4]) ││ RYY(θ[4]) │ ░ ├──────────┤ +q_2: ┤ RZ(θ[2]) ├─░─────────────────────────────┤1 ├┤1 ├─░─┤ RZ(θ[7]) ├ + └──────────┘ ░ └────────────┘└────────────┘ ░ └──────────┘ +``` + +```python +>>> ansatz = ExcitationPreserving(2, reps=1) +>>> qc = QuantumCircuit(2) # create a circuit and append the RY variational form +>>> qc.cry(0.2, 0, 1) # do some previous operation +>>> qc.compose(ansatz, inplace=True) # add the swaprz +>>> qc.draw() + ┌──────────┐┌────────────┐┌────────────┐┌──────────┐ +q_0: ─────■─────┤ RZ(θ[0]) ├┤0 ├┤0 ├┤ RZ(θ[3]) ├ + ┌────┴────┐├──────────┤│ RXX(θ[2]) ││ RYY(θ[2]) │├──────────┤ +q_1: ┤ RY(0.2) ├┤ RZ(θ[1]) ├┤1 ├┤1 ├┤ RZ(θ[4]) ├ + └─────────┘└──────────┘└────────────┘└────────────┘└──────────┘ +``` + +```python +>>> ansatz = ExcitationPreserving(3, reps=1, mode='fsim', entanglement=[[0,2]], +... insert_barriers=True) +>>> print(ansatz) + ┌──────────┐ ░ ┌────────────┐┌────────────┐ ░ ┌──────────┐ +q_0: ┤ RZ(θ[0]) ├─░─┤0 ├┤0 ├─■──────░─┤ RZ(θ[5]) ├ + ├──────────┤ ░ │ ││ │ │ ░ ├──────────┤ +q_1: ┤ RZ(θ[1]) ├─░─┤ RXX(θ[3]) ├┤ RYY(θ[3]) ├─┼──────░─┤ RZ(θ[6]) ├ + ├──────────┤ ░ │ ││ │ │θ[4] ░ ├──────────┤ +q_2: ┤ RZ(θ[2]) ├─░─┤1 ├┤1 ├─■──────░─┤ RZ(θ[7]) ├ + └──────────┘ ░ └────────────┘└────────────┘ ░ └──────────┘ +``` + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits of the ExcitationPreserving circuit. +* **mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Choose the entangler mode, can be ‘iswap’ or ‘fsim’. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Specifies how often the structure of a rotation layer followed by an entanglement layer is repeated. +* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Specifies the entanglement structure. Can be a string (‘full’, ‘linear’ or ‘sca’), a list of integer-pairs specifying the indices of qubits entangled with one another, or a callable returning such a list provided with the index of the entanglement layer. See the Examples section of [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.TwoLocal") for more detail. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A QuantumCircuit object to prepend to the circuit. +* **skip\_unentangled\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, the single qubit gates are only applied to qubits that are entangled with another qubit. If False, the single qubit gates are applied to each qubit in the Ansatz. Defaults to False. +* **skip\_final\_rotation\_layer** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, a rotation layer is added at the end of the ansatz. If False, no rotation layer is added. Defaults to True. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The parameterized gates require a parameter to be defined, for which we use [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector"). +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted in between each layer. If False, no barriers are inserted. +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the selected mode is not supported. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +Return the parameter bounds. + +**Returns** + +The parameter bounds. + + + +### parameters + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.FourierChecking.md b/docs/api/qiskit/0.46/qiskit.circuit.library.FourierChecking.md new file mode 100644 index 00000000000..934e100e187 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.FourierChecking.md @@ -0,0 +1,238 @@ +--- +title: FourierChecking +description: API reference for qiskit.circuit.library.FourierChecking +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.FourierChecking +--- + +# FourierChecking + + + +`qiskit.circuit.library.FourierChecking(f, g)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/fourier_checking.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Fourier checking circuit. + +The circuit for the Fourier checking algorithm, introduced in \[1], involves a layer of Hadamards, the function $f$, another layer of Hadamards, the function $g$, followed by a final layer of Hadamards. The functions $f$ and $g$ are classical functions realized as phase oracles (diagonal operators with \{-1, 1} on the diagonal). + +The probability of observing the all-zeros string is $p(f,g)$. The algorithm solves the promise Fourier checking problem, which decides if f is correlated with the Fourier transform of g, by testing if $p(f,g) <= 0.01$ or $p(f,g) >= 0.05$, promised that one or the other of these is true. + +The functions $f$ and $g$ are currently implemented from their truth tables but could be represented concisely and implemented efficiently for special classes of functions. + +Fourier checking is a special case of $k$-fold forrelation \[2]. + +**Reference:** + +\[1] S. Aaronson, BQP and the Polynomial Hierarchy, 2009 (Section 3.2). [arXiv:0910.4698](https://arxiv.org/abs/0910.4698) + +\[2] S. Aaronson, A. Ambainis, Forrelation: a problem that optimally separates quantum from classical computing, 2014. [arXiv:1411.5729](https://arxiv.org/abs/1411.5729) + +Create Fourier checking circuit. + +**Parameters** + +* **f** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – truth table for f, length 2\*\*n list of \{1,-1}. +* **g** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – truth table for g, length 2\*\*n list of \{1,-1}. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the inputs f and g are not valid. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-FourierChecking-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-FourierChecking-1.png) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 167` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.FunctionalPauliRotations.md b/docs/api/qiskit/0.46/qiskit.circuit.library.FunctionalPauliRotations.md new file mode 100644 index 00000000000..1684121a616 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.FunctionalPauliRotations.md @@ -0,0 +1,188 @@ +--- +title: FunctionalPauliRotations +description: API reference for qiskit.circuit.library.FunctionalPauliRotations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.FunctionalPauliRotations +--- + +# FunctionalPauliRotations + + + +`qiskit.circuit.library.FunctionalPauliRotations(num_state_qubits=None, basis='Y', name='F')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/functional_pauli_rotations.py "view source code") + +Bases: `BlueprintCircuit`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for functional Pauli rotations. + +Create a new functional Pauli rotation circuit. + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits representing the state $|x\rangle$. +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The kind of Pauli rotation to use. Must be ‘X’, ‘Y’ or ‘Z’. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### basis + +The kind of Pauli rotation to be used. + +Set the basis to ‘X’, ‘Y’ or ‘Z’ for controlled-X, -Y, or -Z rotations respectively. + +**Returns** + +The kind of Pauli rotation used in controlled rotation. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 169` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +The minimum number of ancilla qubits in the circuit. + +**Returns** + +The minimal number of ancillas required. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits representing the state $|x\rangle$. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GMS.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GMS.md new file mode 100644 index 00000000000..5f3778d8236 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GMS.md @@ -0,0 +1,247 @@ +--- +title: GMS +description: API reference for qiskit.circuit.library.GMS +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GMS +--- + +# GMS + + + +`qiskit.circuit.library.GMS(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/gms.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Global Mølmer–Sørensen gate. + +**Circuit symbol:** + +```python + ┌───────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 GMS ├ + │ │ +q_2: ┤2 ├ + └───────────┘ +``` + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-GMS-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-GMS-1.png) + +The Mølmer–Sørensen gate is native to ion-trap systems. The global MS can be applied to multiple ions to entangle multiple qubits simultaneously \[1]. + +In the two-qubit case, this is equivalent to an XX(theta) interaction, and is thus reduced to the RXXGate. The global MS gate is a sum of XX interactions on all pairs \[2]. + +$$ +GMS(\chi_{12}, \chi_{13}, ..., \chi_{n-1 n}) = +exp(-i \sum_{i=1}^{n} \sum_{j=i+1}^{n} X{\otimes}X \frac{\chi_{ij}}{2}) +$$ + +**References:** + +\[1] Sørensen, A. and Mølmer, K., Multi-particle entanglement of hot trapped ions. Physical Review Letters. 82 (9): 1835–1838. [arXiv:9810040](https://arxiv.org/abs/quant-ph/9810040) + +\[2] Maslov, D. and Nam, Y., Use of global interactions in efficient quantum circuit constructions. New Journal of Physics, 20(3), p.033018. [arXiv:1707.06356](https://arxiv.org/abs/1707.06356) + +Create a new Global Mølmer–Sørensen (GMS) gate. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – width of gate. +* **theta** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a num\_qubits x num\_qubits symmetric matrix of interaction angles for each qubit pair. The upper triangle is considered. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 170` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GR.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GR.md new file mode 100644 index 00000000000..05a546b6989 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GR.md @@ -0,0 +1,241 @@ +--- +title: GR +description: API reference for qiskit.circuit.library.GR +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GR +--- + +# GR + + + +`qiskit.circuit.library.GR(num_qubits, theta, phi)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/gr.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Global R gate. + +**Circuit symbol:** + +```python + ┌──────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 GR(ϴ,φ) ├ + │ │ +q_2: ┤2 ├ + └──────────┘ +``` + +The global R gate is native to atomic systems (ion traps, cold neutrals). The global R can be applied to multiple qubits simultaneously. + +In the one-qubit case, this is equivalent to an R(theta, phi) operation, and is thus reduced to the RGate. The global R gate is a direct sum of R operations on all individual qubits. + +$$ +GR(\theta, \phi) = \exp(-i \sum_{i=1}^{n} (\cos(\phi)X_i + \sin(\phi)Y_i) \theta/2) +$$ + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-GR-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-GR-1.png) + +Create a new Global R (GR) gate. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – rotation angle about axis determined by phi +* **phi** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – angle of rotation axis in xy-plane + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 179` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GRX.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GRX.md new file mode 100644 index 00000000000..97ceb86234e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GRX.md @@ -0,0 +1,240 @@ +--- +title: GRX +description: API reference for qiskit.circuit.library.GRX +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GRX +--- + +# GRX + + + +`qiskit.circuit.library.GRX(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/gr.py "view source code") + +Bases: [`GR`](qiskit.circuit.library.GR "qiskit.circuit.library.generalized_gates.gr.GR") + +Global RX gate. + +**Circuit symbol:** + +```python + ┌──────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 GRX(ϴ) ├ + │ │ +q_2: ┤2 ├ + └──────────┘ +``` + +The global RX gate is native to atomic systems (ion traps, cold neutrals). The global RX can be applied to multiple qubits simultaneously. + +In the one-qubit case, this is equivalent to an RX(theta) operations, and is thus reduced to the RXGate. The global RX gate is a direct sum of RX operations on all individual qubits. + +$$ +GRX(\theta) = \exp(-i \sum_{i=1}^{n} X_i \theta/2) +$$ + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-GRX-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-GRX-1.png) + +Create a new Global RX (GRX) gate. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – rotation angle about x-axis + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 180` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GRY.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GRY.md new file mode 100644 index 00000000000..ebbf81c46f2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GRY.md @@ -0,0 +1,240 @@ +--- +title: GRY +description: API reference for qiskit.circuit.library.GRY +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GRY +--- + +# GRY + + + +`qiskit.circuit.library.GRY(num_qubits, theta)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/gr.py "view source code") + +Bases: [`GR`](qiskit.circuit.library.GR "qiskit.circuit.library.generalized_gates.gr.GR") + +Global RY gate. + +**Circuit symbol:** + +```python + ┌──────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 GRY(ϴ) ├ + │ │ +q_2: ┤2 ├ + └──────────┘ +``` + +The global RY gate is native to atomic systems (ion traps, cold neutrals). The global RY can be applied to multiple qubits simultaneously. + +In the one-qubit case, this is equivalent to an RY(theta) operation, and is thus reduced to the RYGate. The global RY gate is a direct sum of RY operations on all individual qubits. + +$$ +GRY(\theta) = \exp(-i \sum_{i=1}^{n} Y_i \theta/2) +$$ + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-GRY-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-GRY-1.png) + +Create a new Global RY (GRY) gate. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – rotation angle about y-axis + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 180` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GRZ.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GRZ.md new file mode 100644 index 00000000000..b0e9595effa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GRZ.md @@ -0,0 +1,240 @@ +--- +title: GRZ +description: API reference for qiskit.circuit.library.GRZ +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GRZ +--- + +# GRZ + + + +`qiskit.circuit.library.GRZ(num_qubits, phi)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/gr.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Global RZ gate. + +**Circuit symbol:** + +```python + ┌──────────┐ +q_0: ┤0 ├ + │ │ +q_1: ┤1 GRZ(φ) ├ + │ │ +q_2: ┤2 ├ + └──────────┘ +``` + +The global RZ gate is native to atomic systems (ion traps, cold neutrals). The global RZ can be applied to multiple qubits simultaneously. + +In the one-qubit case, this is equivalent to an RZ(phi) operation, and is thus reduced to the RZGate. The global RZ gate is a direct sum of RZ operations on all individual qubits. + +$$ +GRZ(\phi) = \exp(-i \sum_{i=1}^{n} Z_i \phi) +$$ + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-GRZ-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-GRZ-1.png) + +Create a new Global RZ (GRZ) gate. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **phi** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – rotation angle about z-axis + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 190` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GlobalPhaseGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GlobalPhaseGate.md new file mode 100644 index 00000000000..b3e0d99bcf4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GlobalPhaseGate.md @@ -0,0 +1,145 @@ +--- +title: GlobalPhaseGate +description: API reference for qiskit.circuit.library.GlobalPhaseGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GlobalPhaseGate +--- + +# GlobalPhaseGate + + + +`qiskit.circuit.library.GlobalPhaseGate(phase, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/global_phase.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +The global phase gate ($e^{i\theta}$). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Mathematical Representation:** + +$$ +\text{GlobalPhaseGate}\ = + \begin{pmatrix} + e^{i\theta} + \end{pmatrix} + + +$$ + +**Parameters** + +* **phase** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The value of phase it takes. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – An optional label for the gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.GlobalPhaseGate.base_class "qiskit.circuit.library.GlobalPhaseGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted GLobalPhaseGate gate. + +$\text{GlobalPhaseGate}(\lambda)^{\dagger} = \text{GlobalPhaseGate}(-\lambda)$ + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GraphState.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GraphState.md new file mode 100644 index 00000000000..38157921792 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GraphState.md @@ -0,0 +1,245 @@ +--- +title: GraphState +description: API reference for qiskit.circuit.library.GraphState +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GraphState +--- + +# GraphState + + + +`qiskit.circuit.library.GraphState(adjacency_matrix)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/graph_state.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Circuit to prepare a graph state. + +Given a graph G = (V, E), with the set of vertices V and the set of edges E, the corresponding graph state is defined as + +$$ +|G\rangle = \prod_{(a,b) \in E} CZ_{(a,b)} {|+\rangle}^{\otimes V} +$$ + +Such a state can be prepared by first preparing all qubits in the $+$ state, then applying a $CZ$ gate for each corresponding graph edge. + +Graph state preparation circuits are Clifford circuits, and thus easy to simulate classically. However, by adding a layer of measurements in a product basis at the end, there is evidence that the circuit becomes hard to simulate \[2]. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-GraphState-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-GraphState-1.png) + +**References:** + +**\[1] M. Hein, J. Eisert, H.J. Briegel, Multi-party Entanglement in Graph States,** + +[arXiv:0307130](https://arxiv.org/pdf/quant-ph/0307130.pdf) + +**\[2] D. Koh, Further Extensions of Clifford Circuits & their Classical Simulation Complexities.** + +[arXiv:1512.07892](https://arxiv.org/pdf/1512.07892.pdf) + +Create graph state preparation circuit. + +**Parameters** + +**adjacency\_matrix** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *| np.ndarray*) – input graph as n-by-n list of 0-1 lists + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If adjacency\_matrix is not symmetric. + +The circuit prepares a graph state with the given adjacency matrix. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 195` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.GroverOperator.md b/docs/api/qiskit/0.46/qiskit.circuit.library.GroverOperator.md new file mode 100644 index 00000000000..90d206d52b4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.GroverOperator.md @@ -0,0 +1,380 @@ +--- +title: GroverOperator +description: API reference for qiskit.circuit.library.GroverOperator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.GroverOperator +--- + +# GroverOperator + + + +`qiskit.circuit.library.GroverOperator(oracle, state_preparation=None, zero_reflection=None, reflection_qubits=None, insert_barriers=False, mcx_mode='noancilla', name='Q')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/grover_operator.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +The Grover operator. + +Grover’s search algorithm \[1, 2] consists of repeated applications of the so-called Grover operator used to amplify the amplitudes of the desired output states. This operator, $\mathcal{Q}$, consists of the phase oracle, $\mathcal{S}_f$, zero phase-shift or zero reflection, $\mathcal{S}_0$, and an input state preparation $\mathcal{A}$: + +$$ +\mathcal{Q} = \mathcal{A} \mathcal{S}_0 \mathcal{A}^\dagger \mathcal{S}_f + + +$$ + +In the standard Grover search we have $\mathcal{A} = H^{\otimes n}$: + +$$ +\mathcal{Q} = H^{\otimes n} \mathcal{S}_0 H^{\otimes n} \mathcal{S}_f + = D \mathcal{S_f} + + +$$ + +The operation $D = H^{\otimes n} \mathcal{S}_0 H^{\otimes n}$ is also referred to as diffusion operator. In this formulation we can see that Grover’s operator consists of two steps: first, the phase oracle multiplies the good states by -1 (with $\mathcal{S}_f$) and then the whole state is reflected around the mean (with $D$). + +This class allows setting a different state preparation, as in quantum amplitude amplification (a generalization of Grover’s algorithm), $\mathcal{A}$ might not be a layer of Hardamard gates \[3]. + +The action of the phase oracle $\mathcal{S}_f$ is defined as + +$$ +\mathcal{S}_f: |x\rangle \mapsto (-1)^{f(x)}|x\rangle + + +$$ + +where $f(x) = 1$ if $x$ is a good state and 0 otherwise. To highlight the fact that this oracle flips the phase of the good states and does not flip the state of a result qubit, we call $\mathcal{S}_f$ a phase oracle. + +Note that you can easily construct a phase oracle from a bitflip oracle by sandwiching the controlled X gate on the result qubit by a X and H gate. For instance + +```python +Bitflip oracle Phaseflip oracle +q_0: ──■── q_0: ────────────■──────────── + ┌─┴─┐ ┌───┐┌───┐┌─┴─┐┌───┐┌───┐ +out: ┤ X ├ out: ┤ X ├┤ H ├┤ X ├┤ H ├┤ X ├ + └───┘ └───┘└───┘└───┘└───┘└───┘ +``` + +There is some flexibility in defining the oracle and $\mathcal{A}$ operator. Before the Grover operator is applied in Grover’s algorithm, the qubits are first prepared with one application of the $\mathcal{A}$ operator (or Hadamard gates in the standard formulation). Thus, we always have operation of the form $\mathcal{A} \mathcal{S}_f \mathcal{A}^\dagger$. Therefore it is possible to move bitflip logic into $\mathcal{A}$ and leaving the oracle only to do phaseflips via Z gates based on the bitflips. One possible use-case for this are oracles that do not uncompute the state qubits. + +The zero reflection $\mathcal{S}_0$ is usually defined as + +$$ +\mathcal{S}_0 = 2 |0\rangle^{\otimes n} \langle 0|^{\otimes n} - \mathbb{I}_n + + +$$ + +where $\mathbb{I}_n$ is the identity on $n$ qubits. By default, this class implements the negative version $2 |0\rangle^{\otimes n} \langle 0|^{\otimes n} - \mathbb{I}_n$, since this can simply be implemented with a multi-controlled Z sandwiched by X gates on the target qubit and the introduced global phase does not matter for Grover’s algorithm. + +**Examples** + +```python +>>> from qiskit.circuit import QuantumCircuit +>>> from qiskit.circuit.library import GroverOperator +>>> oracle = QuantumCircuit(2) +>>> oracle.z(0) # good state = first qubit is |1> +>>> grover_op = GroverOperator(oracle, insert_barriers=True) +>>> grover_op.decompose().draw() + ┌───┐ ░ ┌───┐ ░ ┌───┐ ┌───┐ ░ ┌───┐ +state_0: ┤ Z ├─░─┤ H ├─░─┤ X ├───────■──┤ X ├──────░─┤ H ├ + └───┘ ░ ├───┤ ░ ├───┤┌───┐┌─┴─┐├───┤┌───┐ ░ ├───┤ +state_1: ──────░─┤ H ├─░─┤ X ├┤ H ├┤ X ├┤ H ├┤ X ├─░─┤ H ├ + ░ └───┘ ░ └───┘└───┘└───┘└───┘└───┘ ░ └───┘ +``` + +```python +>>> oracle = QuantumCircuit(1) +>>> oracle.z(0) # the qubit state |1> is the good state +>>> state_preparation = QuantumCircuit(1) +>>> state_preparation.ry(0.2, 0) # non-uniform state preparation +>>> grover_op = GroverOperator(oracle, state_preparation) +>>> grover_op.decompose().draw() + ┌───┐┌──────────┐┌───┐┌───┐┌───┐┌─────────┐ +state_0: ┤ Z ├┤ RY(-0.2) ├┤ X ├┤ Z ├┤ X ├┤ RY(0.2) ├ + └───┘└──────────┘└───┘└───┘└───┘└─────────┘ +``` + +```python +>>> oracle = QuantumCircuit(4) +>>> oracle.z(3) +>>> reflection_qubits = [0, 3] +>>> state_preparation = QuantumCircuit(4) +>>> state_preparation.cry(0.1, 0, 3) +>>> state_preparation.ry(0.5, 3) +>>> grover_op = GroverOperator(oracle, state_preparation, +... reflection_qubits=reflection_qubits) +>>> grover_op.decompose().draw() + ┌───┐ ┌───┐ +state_0: ──────────────────────■──────┤ X ├───────■──┤ X ├──────────■──────────────── + │ └───┘ │ └───┘ │ +state_1: ──────────────────────┼──────────────────┼─────────────────┼──────────────── + │ │ │ +state_2: ──────────────────────┼──────────────────┼─────────────────┼──────────────── + ┌───┐┌──────────┐┌────┴─────┐┌───┐┌───┐┌─┴─┐┌───┐┌───┐┌────┴────┐┌─────────┐ +state_3: ┤ Z ├┤ RY(-0.5) ├┤ RY(-0.1) ├┤ X ├┤ H ├┤ X ├┤ H ├┤ X ├┤ RY(0.1) ├┤ RY(0.5) ├ + └───┘└──────────┘└──────────┘└───┘└───┘└───┘└───┘└───┘└─────────┘└─────────┘ +``` + +```python +>>> mark_state = Statevector.from_label('011') +>>> diffuse_operator = 2 * DensityMatrix.from_label('000') - Operator.from_label('III') +>>> grover_op = GroverOperator(oracle=mark_state, zero_reflection=diffuse_operator) +>>> grover_op.decompose().draw(fold=70) + ┌─────────────────┐ ┌───┐ » +state_0: ┤0 ├──────┤ H ├──────────────────────────» + │ │┌─────┴───┴─────┐ ┌───┐ » +state_1: ┤1 UCRZ(0,pi,0,0) ├┤0 ├─────┤ H ├──────────» + │ ││ UCRZ(pi/2,0) │┌────┴───┴────┐┌───┐» +state_2: ┤2 ├┤1 ├┤ UCRZ(-pi/4) ├┤ H ├» + └─────────────────┘└───────────────┘└─────────────┘└───┘» +« ┌─────────────────┐ ┌───┐ +«state_0: ┤0 ├──────┤ H ├───────────────────────── +« │ │┌─────┴───┴─────┐ ┌───┐ +«state_1: ┤1 UCRZ(pi,0,0,0) ├┤0 ├────┤ H ├────────── +« │ ││ UCRZ(pi/2,0) │┌───┴───┴────┐┌───┐ +«state_2: ┤2 ├┤1 ├┤ UCRZ(pi/4) ├┤ H ├ +« └─────────────────┘└───────────────┘└────────────┘└───┘ +``` + +**References** + +**\[1]: L. K. Grover (1996), A fast quantum mechanical algorithm for database search,** + +[arXiv:quant-ph/9605043](https://arxiv.org/abs/quant-ph/9605043). + +**\[2]: I. Chuang & M. Nielsen, Quantum Computation and Quantum Information,** + +Cambridge: Cambridge University Press, 2000. Chapter 6.1.2. + +**\[3]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000).** + +Quantum Amplitude Amplification and Estimation. [arXiv:quant-ph/0005055](http://arxiv.org/abs/quant-ph/0005055). + +**Parameters** + +* **oracle** (*Union\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*,* [*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")*]*) – The phase oracle implementing a reflection about the bad state. Note that this is not a bitflip oracle, see the docstring for more information. +* **state\_preparation** (*Optional\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The operator preparing the good and bad state. For Grover’s algorithm, this is a n-qubit Hadamard gate and for amplitude amplification or estimation the operator $\mathcal{A}$. +* **zero\_reflection** (*Optional\[Union\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*,* [*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")*,* [*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")*]]*) – The reflection about the zero state, $\mathcal{S}_0$. +* **reflection\_qubits** (*Optional\[List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Qubits on which the zero reflection acts on. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether barriers should be inserted between the reflections and A. +* **mcx\_mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The mode to use for building the default zero reflection. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 197` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### oracle + +The oracle implementing a reflection about the bad state. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reflection\_qubits + +Reflection qubits, on which S0 is applied (if S0 is not user-specified). + + + +### state\_preparation + +The subcircuit implementing the A operator or Hadamards. + + + +### zero\_reflection + +The subcircuit implementing the reflection about 0. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.HGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.HGate.md new file mode 100644 index 00000000000..5c77f0b5226 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.HGate.md @@ -0,0 +1,173 @@ +--- +title: HGate +description: API reference for qiskit.circuit.library.HGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.HGate +--- + +# HGate + + + +`qiskit.circuit.library.HGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/h.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Single-qubit Hadamard gate. + +This gate is a pi rotation about the X+Z axis, and has the effect of changing computation basis from $|0\rangle,|1\rangle$ to $|+\rangle,|-\rangle$ and vice-versa. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`h()`](qiskit.circuit.QuantumCircuit#h "qiskit.circuit.QuantumCircuit.h") method. + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ H ├ + └───┘ +``` + +**Matrix Representation:** + +$$ +H = \frac{1}{\sqrt{2}} + \begin{pmatrix} + 1 & 1 \\ + 1 & -1 + \end{pmatrix} +$$ + +Create new H gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.HGate.base_class "qiskit.circuit.library.HGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-H gate. + +One control qubit returns a CH gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted H gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.HRSCumulativeMultiplier.md b/docs/api/qiskit/0.46/qiskit.circuit.library.HRSCumulativeMultiplier.md new file mode 100644 index 00000000000..c81fb1044d6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.HRSCumulativeMultiplier.md @@ -0,0 +1,277 @@ +--- +title: HRSCumulativeMultiplier +description: API reference for qiskit.circuit.library.HRSCumulativeMultiplier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.HRSCumulativeMultiplier +--- + +# HRSCumulativeMultiplier + + + +`qiskit.circuit.library.HRSCumulativeMultiplier(num_state_qubits, num_result_qubits=None, adder=None, name='HRSCumulativeMultiplier')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/multipliers/hrs_cumulative_multiplier.py "view source code") + +Bases: `Multiplier` + +A multiplication circuit to store product of two input registers out-of-place. + +Circuit uses the approach from \[1]. As an example, a multiplier circuit that performs a non-modular multiplication on two 3-qubit sized registers with the default adder is as follows (where `Adder` denotes the `CDKMRippleCarryAdder`): + +```python + a_0: ────■───────────────────────── + │ + a_1: ────┼─────────■─────────────── + │ │ + a_2: ────┼─────────┼─────────■───── + ┌───┴────┐┌───┴────┐┌───┴────┐ + b_0: ┤0 ├┤0 ├┤0 ├ + │ ││ ││ │ + b_1: ┤1 ├┤1 ├┤1 ├ + │ ││ ││ │ + b_2: ┤2 ├┤2 ├┤2 ├ + │ ││ ││ │ +out_0: ┤3 ├┤ ├┤ ├ + │ ││ ││ │ +out_1: ┤4 ├┤3 ├┤ ├ + │ Adder ││ Adder ││ Adder │ +out_2: ┤5 ├┤4 ├┤3 ├ + │ ││ ││ │ +out_3: ┤6 ├┤5 ├┤4 ├ + │ ││ ││ │ +out_4: ┤ ├┤6 ├┤5 ├ + │ ││ ││ │ +out_5: ┤ ├┤ ├┤6 ├ + │ ││ ││ │ +aux_0: ┤7 ├┤7 ├┤7 ├ + └────────┘└────────┘└────────┘ +``` + +Multiplication in this circuit is implemented in a classical approach by performing a series of shifted additions using one of the input registers while the qubits from the other input register act as control qubits for the adders. + +**References:** + +\[1] Häner et al., Optimizing Quantum Circuits for Arithmetic, 2018. [arXiv:1805.12445](https://arxiv.org/pdf/1805.12445.pdf) + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits in either input register for state $|a\rangle$ or $|b\rangle$. The two input registers must have the same number of qubits. +* **num\_result\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of result qubits to limit the output to. If number of result qubits is $n$, multiplication modulo $2^n$ is performed to limit the output to the specified number of qubits. Default value is `2 * num_state_qubits` to represent any possible result from the multiplication of the two inputs. +* **adder** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *| None*) – Half adder circuit to be used for performing multiplication. The CDKMRippleCarryAdder is used as default if no adder is provided. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If `num_result_qubits` is not default and a custom adder is provided. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 197` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### num\_result\_qubits + +The number of result qubits to limit the output to. + +**Returns** + +The number of result qubits. + + + +### num\_state\_qubits + +The number of state qubits, i.e. the number of bits in each input register. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.HamiltonianGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.HamiltonianGate.md new file mode 100644 index 00000000000..238f01bb122 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.HamiltonianGate.md @@ -0,0 +1,181 @@ +--- +title: HamiltonianGate +description: API reference for qiskit.circuit.library.HamiltonianGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.HamiltonianGate +--- + +# HamiltonianGate + + + +`qiskit.circuit.library.HamiltonianGate(data, time, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/hamiltonian_gate.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Class for representing evolution by a Hamiltonian operator as a gate. + +This gate resolves to a [`UnitaryGate`](qiskit.circuit.library.UnitaryGate "qiskit.circuit.library.UnitaryGate") as $U(t) = \exp(-i t H)$, which can be decomposed into basis gates if it is 2 qubits or less, or simulated directly in Aer for more qubits. + +**Parameters** + +* **data** (*np.ndarray |* [*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate") *| BaseOperator*) – A hermitian operator. +* **time** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")) – Time evolution parameter. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Unitary name for backend \[Default: None]. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if input data is not an N-qubit unitary operator. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.HamiltonianGate.base_class "qiskit.circuit.library.HamiltonianGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the unitary. + +### conjugate + + + +`conjugate()` + +Return the conjugate of the Hamiltonian. + +### inverse + + + +`inverse()` + +Return the adjoint of the unitary. + +### qasm + + + +`qasm()` + +Raise an error, as QASM is not defined for the HamiltonianGate. + + + The method `qiskit.circuit.library.hamiltonian_gate.HamiltonianGate.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. + + +### transpose + + + +`transpose()` + +Return the transpose of the Hamiltonian. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Hamiltonian parameter has to be an ndarray, operator or float. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.HiddenLinearFunction.md b/docs/api/qiskit/0.46/qiskit.circuit.library.HiddenLinearFunction.md new file mode 100644 index 00000000000..fd6852f11f6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.HiddenLinearFunction.md @@ -0,0 +1,247 @@ +--- +title: HiddenLinearFunction +description: API reference for qiskit.circuit.library.HiddenLinearFunction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.HiddenLinearFunction +--- + +# HiddenLinearFunction + + + +`qiskit.circuit.library.HiddenLinearFunction(adjacency_matrix)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/hidden_linear_function.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Circuit to solve the hidden linear function problem. + +The 2D Hidden Linear Function problem is determined by a 2D adjacency matrix A, where only elements that are nearest-neighbor on a grid have non-zero entries. Each row/column corresponds to one binary variable $x_i$. + +The hidden linear function problem is as follows: + +Consider the quadratic form + +$$ +q(x) = \sum_{i,j=1}^{n}{x_i x_j} ~(\mathrm{mod}~ 4) +$$ + +and restrict $q(x)$ onto the nullspace of A. This results in a linear function. + +$$ +2 \sum_{i=1}^{n}{z_i x_i} ~(\mathrm{mod}~ 4) \forall x \in \mathrm{Ker}(A) +$$ + +and the goal is to recover this linear function (equivalently a vector $[z_0, ..., z_{n-1}]$). There can be multiple solutions. + +In \[1] it is shown that the present circuit solves this problem on a quantum computer in constant depth, whereas any corresponding solution on a classical computer would require circuits that grow logarithmically with $n$. Thus this circuit is an example of quantum advantage with shallow circuits. + +**Reference Circuit:** + +> ![../\_images/qiskit-circuit-library-HiddenLinearFunction-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-HiddenLinearFunction-1.png) + +**Reference:** + +\[1] S. Bravyi, D. Gosset, R. Koenig, Quantum Advantage with Shallow Circuits, 2017. [arXiv:1704.00690](https://arxiv.org/abs/1704.00690) + +Create new HLF circuit. + +**Parameters** + +**adjacency\_matrix** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a symmetric n-by-n list of 0-1 lists. n will be the number of qubits. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If A is not symmetric. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 199` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.IGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.IGate.md new file mode 100644 index 00000000000..8616cf72a7d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.IGate.md @@ -0,0 +1,156 @@ +--- +title: IGate +description: API reference for qiskit.circuit.library.IGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.IGate +--- + +# IGate + + + +`qiskit.circuit.library.IGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/i.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Identity gate. + +Identity gate corresponds to a single-qubit gate wait cycle, and should not be optimized or unrolled (it is an opaque gate). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`i()`](qiskit.circuit.QuantumCircuit#i "qiskit.circuit.QuantumCircuit.i") and [`id()`](qiskit.circuit.QuantumCircuit#id "qiskit.circuit.QuantumCircuit.id") methods. + +**Matrix Representation:** + +$$ +I = \begin{pmatrix} + 1 & 0 \\ + 0 & 1 + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ I ├ + └───┘ +``` + +Create new Identity gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.IGate.base_class "qiskit.circuit.library.IGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Invert this gate. + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.IQP.md b/docs/api/qiskit/0.46/qiskit.circuit.library.IQP.md new file mode 100644 index 00000000000..7dc7738ae27 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.IQP.md @@ -0,0 +1,235 @@ +--- +title: IQP +description: API reference for qiskit.circuit.library.IQP +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.IQP +--- + +# IQP + + + +`qiskit.circuit.library.IQP(interactions)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/iqp.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Instantaneous quantum polynomial (IQP) circuit. + +The circuit consists of a column of Hadamard gates, a column of powers of T gates, a sequence of powers of CS gates (up to $\frac{n^2-n}{2}$ of them), and a final column of Hadamard gates, as introduced in \[1]. + +The circuit is parameterized by an n x n interactions matrix. The powers of each T gate are given by the diagonal elements of the interactions matrix. The powers of the CS gates are given by the upper triangle of the interactions matrix. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-IQP-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-IQP-1.png) + +**Expanded Circuit:** + +> ![../\_images/qiskit-circuit-library-IQP-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-IQP-2.png) + +**References:** + +\[1] M. J. Bremner et al. Average-case complexity versus approximate simulation of commuting quantum computations, Phys. Rev. Lett. 117, 080501 (2016). [arXiv:1504.07999](https://arxiv.org/abs/1504.07999) + +Create IQP circuit. + +**Parameters** + +**interactions** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *| np.ndarray*) – input n-by-n symmetric matrix. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the inputs is not as symmetric matrix. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 204` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Initialize.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Initialize.md new file mode 100644 index 00000000000..61548344e8d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Initialize.md @@ -0,0 +1,170 @@ +--- +title: Initialize +description: API reference for qiskit.circuit.library.Initialize +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Initialize +--- + +# Initialize + + + +`qiskit.circuit.library.Initialize(params, num_qubits=None, normalize=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/data_preparation/initializer.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Complex amplitude initialization. + +Class that initializes some flexible collection of qubit registers, implemented by calling the [`StatePreparation`](qiskit.circuit.library.StatePreparation "qiskit.circuit.library.StatePreparation") class. Note that `Initialize` is an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") and not a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") since it contains a reset instruction, which is not unitary. + +**Parameters** + +* **params** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *| Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – + + The state to initialize to, can be either of the following. + + * Statevector or vector of complex amplitudes to initialize to. + * Labels of basis states of the Pauli eigenstates Z, X, Y. See [`Statevector.from_label()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label"). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to $|1\rangle$ and the qubit one to $|0\rangle$. + * An integer that is used as a bitmap indicating which qubits to initialize to $|1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $|1\rangle$ and qubit 1 to $|0\rangle$. + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – This parameter is only used if params is an int. Indicates the total number of qubits in the initialize call. Example: initialize covers 5 qubits and params is 3. This allows qubits 0 and 1 to be initialized to $|1\rangle$ and the remaining 3 qubits to be initialized to $|0\rangle$. + +* **normalize** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to normalize an input array to a unit vector. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.Initialize.base_class "qiskit.circuit.library.Initialize.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Return initialize params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### gates\_to\_uncompute + + + +`gates_to_uncompute()` + +Call to create a circuit with gates that take the desired vector to zero. + +**Returns** + +Circuit to take `self.params` vector to $|{00\ldots0}\rangle$ + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.InnerProduct.md b/docs/api/qiskit/0.46/qiskit.circuit.library.InnerProduct.md new file mode 100644 index 00000000000..19811da0aa3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.InnerProduct.md @@ -0,0 +1,246 @@ +--- +title: InnerProduct +description: API reference for qiskit.circuit.library.InnerProduct +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.InnerProduct +--- + +# InnerProduct + + + +`qiskit.circuit.library.InnerProduct(num_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/boolean_logic/inner_product.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +A 2n-qubit Boolean function that computes the inner product of two n-qubit vectors over $F_2$. + +This implementation is a phase oracle which computes the following transform. + +$$ +\mathcal{IP}_{2n} : F_2^{2n} \rightarrow {-1, 1} +\mathcal{IP}_{2n}(x_1, \cdots, x_n, y_1, \cdots, y_n) = (-1)^{x.y} +$$ + +The corresponding unitary is a diagonal, which induces a -1 phase on any inputs where the inner product of the top and bottom registers is 1. Otherwise it keeps the input intact. + +```python +q0_0: ─■────────── + │ +q0_1: ─┼──■─────── + │ │ +q0_2: ─┼──┼──■──── + │ │ │ +q0_3: ─┼──┼──┼──■─ + │ │ │ │ +q1_0: ─■──┼──┼──┼─ + │ │ │ +q1_1: ────■──┼──┼─ + │ │ +q1_2: ───────■──┼─ + │ +q1_3: ──────────■─ +``` + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-InnerProduct-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-InnerProduct-1.png) + +Return a circuit to compute the inner product of 2 n-qubit registers. + +**Parameters** + +**num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – width of top and bottom registers (half total circuit width) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 161` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.IntegerComparator.md b/docs/api/qiskit/0.46/qiskit.circuit.library.IntegerComparator.md new file mode 100644 index 00000000000..adf614c8b63 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.IntegerComparator.md @@ -0,0 +1,201 @@ +--- +title: IntegerComparator +description: API reference for qiskit.circuit.library.IntegerComparator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.IntegerComparator +--- + +# IntegerComparator + + + +`qiskit.circuit.library.IntegerComparator(num_state_qubits=None, value=None, geq=True, name='cmp')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/integer_comparator.py "view source code") + +Bases: `BlueprintCircuit` + +Integer Comparator. + +Operator compares basis states $|i\rangle_n$ against a classically given integer $L$ of fixed value and flips a target qubit if $i \geq L$ (or $<$ depending on the parameter `geq`): + +$$ +|i\rangle_n |0\rangle \mapsto |i\rangle_n |i \geq L\rangle +$$ + +This operation is based on two’s complement implementation of binary subtraction but only uses carry bits and no actual result bits. If the most significant carry bit (the results bit) is 1, the $\geq$ condition is `True` otherwise it is `False`. + +Create a new fixed value comparator circuit. + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Number of state qubits. If this is set it will determine the number of qubits required for the circuit. +* **value** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The fixed value to compare with. +* **geq** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, evaluate a `>=` condition, else `<`. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### geq + +Return whether the comparator compares greater or less equal. + +**Returns** + +True, if the comparator compares `>=`, False if `<`. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 163` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +Deprecated. Use num\_ancillas instead. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of qubits encoding the state for the comparison. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### value + +The value to compare the qubit register to. + +**Returns** + +The value against which the value of the qubit register is compared. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Isometry.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Isometry.md new file mode 100644 index 00000000000..01f4b2657e9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Isometry.md @@ -0,0 +1,174 @@ +--- +title: Isometry +description: API reference for qiskit.circuit.library.Isometry +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Isometry +--- + +# Isometry + + + +`qiskit.circuit.library.Isometry(isometry, num_ancillas_zero, num_ancillas_dirty, epsilon=1e-10)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/isometry.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Decomposition of arbitrary isometries from $m$ to $n$ qubits. + +In particular, this allows to decompose unitaries (m=n) and to do state preparation ($m=0$). + +The decomposition is based on \[1]. + +**References:** + +**\[1] Iten et al., Quantum circuits for isometries (2016).** + +[Phys. Rev. A 93, 032318](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.93.032318). + +**Parameters** + +* **isometry** (*np.ndarray*) – An isometry from $m$ to :math\`n\` qubits, i.e., a complex `np.ndarray` of dimension $2^n \times 2^m$ with orthonormal columns (given in the computational basis specified by the order of the ancillas and the input qubits, where the ancillas are considered to be more significant than the input qubits). +* **num\_ancillas\_zero** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of additional ancillas that start in the state $|0\rangle$ (the $n-m$ ancillas required for providing the output of the isometry are not accounted for here). +* **num\_ancillas\_dirty** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of additional ancillas that start in an arbitrary state. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Error tolerance of calculations. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.Isometry.base_class "qiskit.circuit.library.Isometry.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inv\_gate + + + +`inv_gate()` + +Return the adjoint of the unitary. + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Isometry parameter has to be an ndarray. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.LinearAmplitudeFunction.md b/docs/api/qiskit/0.46/qiskit.circuit.library.LinearAmplitudeFunction.md new file mode 100644 index 00000000000..62fa6a465d5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.LinearAmplitudeFunction.md @@ -0,0 +1,283 @@ +--- +title: LinearAmplitudeFunction +description: API reference for qiskit.circuit.library.LinearAmplitudeFunction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.LinearAmplitudeFunction +--- + +# LinearAmplitudeFunction + + + +`qiskit.circuit.library.LinearAmplitudeFunction(num_state_qubits, slope, offset, domain, image, rescaling_factor=1, breakpoints=None, name='F')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/linear_amplitude_function.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +A circuit implementing a (piecewise) linear function on qubit amplitudes. + +An amplitude function $F$ of a function $f$ is a mapping + +$$ +F|x\rangle|0\rangle = \sqrt{1 - \hat{f}(x)} |x\rangle|0\rangle + \sqrt{\hat{f}(x)} + |x\rangle|1\rangle. +$$ + +for a function $\hat{f}: \{ 0, ..., 2^n - 1 \} \rightarrow [0, 1]$, where $|x\rangle$ is a $n$ qubit state. + +This circuit implements $F$ for piecewise linear functions $\hat{f}$. In this case, the mapping $F$ can be approximately implemented using a Taylor expansion and linearly controlled Pauli-Y rotations, see \[1, 2] for more detail. This approximation uses a `rescaling_factor` to determine the accuracy of the Taylor expansion. + +In general, the function of interest $f$ is defined from some interval $[a,b]$, the `domain` to $[c,d]$, the `image`, instead of $\{ 1, ..., N \}$ to $[0, 1]$. Using an affine transformation we can rescale $f$ to $\hat{f}$: + +$$ +\hat{f}(x) = \frac{f(\phi(x)) - c}{d - c} +$$ + +with + +$$ +\phi(x) = a + \frac{b - a}{2^n - 1} x. +$$ + +If $f$ is a piecewise linear function on $m$ intervals $[p_{i-1}, p_i], i \in \{1, ..., m\}$ with slopes $\alpha_i$ and offsets $\beta_i$ it can be written as + +$$ +f(x) = \sum_{i=1}^m 1_{[p_{i-1}, p_i]}(x) (\alpha_i x + \beta_i) +$$ + +where $1_{[a, b]}$ is an indication function that is 1 if the argument is in the interval $[a, b]$ and otherwise 0. The breakpoints $p_i$ can be specified by the `breakpoints` argument. + +**References** + +**\[1]: Woerner, S., & Egger, D. J. (2018).** + +Quantum Risk Analysis. [arXiv:1806.06893](http://arxiv.org/abs/1806.06893) + +**\[2]: Gacon, J., Zoufal, C., & Woerner, S. (2020).** + +Quantum-Enhanced Simulation-Based Optimization. [arXiv:2005.10780](http://arxiv.org/abs/2005.10780) + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits used to encode the variable $x$. +* **slope** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The slope of the linear function. Can be a list of slopes if it is a piecewise linear function. +* **offset** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The offset of the linear function. Can be a list of offsets if it is a piecewise linear function. +* **domain** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The domain of the function as tuple $(x_\min{}, x_\max{})$. +* **image** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The image of the function as tuple $(f_\min{}, f_\max{})$. +* **rescaling\_factor** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rescaling factor to adjust the accuracy in the Taylor approximation. +* **breakpoints** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – The breakpoints if the function is piecewise linear. If None, the function is not piecewise. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 163` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### post\_processing + + + +`post_processing(scaled_value)` + +Map the function value of the approximated $\hat{f}$ to $f$. + +**Parameters** + +**scaled\_value** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – A function value from the Taylor expansion of $\hat{f}(x)$. + +**Returns** + +The `scaled_value` mapped back to the domain of $f$, by first inverting the transformation used for the Taylor approximation and then mapping back from $[0, 1]$ to the original domain. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.LinearFunction.md b/docs/api/qiskit/0.46/qiskit.circuit.library.LinearFunction.md new file mode 100644 index 00000000000..626008c96ca --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.LinearFunction.md @@ -0,0 +1,251 @@ +--- +title: LinearFunction +description: API reference for qiskit.circuit.library.LinearFunction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.LinearFunction +--- + +# LinearFunction + + + +`qiskit.circuit.library.LinearFunction(linear, validate_input=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/linear_function.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A linear reversible circuit on n qubits. + +Internally, a linear function acting on n qubits is represented as a n x n matrix of 0s and 1s in numpy array format. + +A linear function can be synthesized into CX and SWAP gates using the Patel–Markov–Hayes algorithm, as implemented in [`synth_cnot_count_full_pmh()`](synthesis#qiskit.synthesis.synth_cnot_count_full_pmh "qiskit.synthesis.synth_cnot_count_full_pmh") based on reference \[1]. + +For efficiency, the internal n x n matrix is stored in the format expected by cnot\_synth, which is the big-endian (and not the little-endian) bit-ordering convention. + +**Example:** the circuit + +```python +q_0: ──■── + ┌─┴─┐ +q_1: ┤ X ├ + └───┘ +q_2: ───── +``` + +is represented by a 3x3 linear matrix + +$$ +\begin{pmatrix} + 1 & 0 & 0 \\ + 1 & 1 & 0 \\ + 0 & 0 & 1 +\end{pmatrix} +$$ + +**References:** + +\[1] Ketan N. Patel, Igor L. Markov, and John P. Hayes, Optimal synthesis of linear reversible circuits, Quantum Inf. Comput. 8(3) (2008). [Online at umich.edu.](https://web.eecs.umich.edu/~imarkov/pubs/jour/qic08-cnot.pdf) + +Create a new linear function. + +**Parameters** + +* **linear** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*] | np.ndarray\[*[*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*] |* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*LinearFunction*](#qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction") *|*[*PermutationGate*](qiskit.circuit.library.PermutationGate "qiskit.circuit.library.PermutationGate") *|*[*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – data from which a linear function can be constructed. It can be either a nxn matrix (describing the linear transformation), a permutation (which is a special case of a linear function), another linear function, a clifford (when it corresponds to a linear function), or a quantum circuit composed of linear gates (CX and SWAP) and other objects described above, including nested subcircuits. +* **validate\_input** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, performs more expensive input validation checks, such as checking that a given n x n matrix is invertible. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the input is invalid: either the input matrix is not square or not invertible, or the input quantum circuit contains non-linear objects (for example, a Hadamard gate, or a Clifford that does not correspond to a linear function). + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.LinearFunction.base_class "qiskit.circuit.library.LinearFunction.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### linear + +Returns the n x n matrix representing this linear function. + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### original\_circuit + +Returns the original circuit used to construct this linear function (including None, when the linear function is not constructed from a circuit). + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### extend\_with\_identity + + + +`extend_with_identity(num_qubits, positions)` + +Extend linear function to a linear function over nq qubits, with identities on other subsystems. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits of the extended function. +* **positions** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – describes the positions of original qubits in the extended function’s qubits. + +**Returns** + +extended linear function. + +**Return type** + +[LinearFunction](#qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction") + +### function\_str + + + +`function_str()` + +Return string representation of the linear function viewed as a linear transformation. + +### is\_permutation + + + +`is_permutation()` + +Returns whether this linear function is a permutation, that is whether every row and every column of the n x n matrix has exactly one 1. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### mat\_str + + + +`mat_str()` + +Return string representation of the linear function viewed as a matrix with 0/1 entries. + +### permutation\_pattern + + + +`permutation_pattern()` + +This method first checks if a linear function is a permutation and raises a qiskit.circuit.exceptions.CircuitError if not. In the case that this linear function is a permutation, returns the permutation pattern. + +### synthesize + + + +`synthesize()` + +Synthesizes the linear function into a quantum circuit. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Parameter validation + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.LinearPauliRotations.md b/docs/api/qiskit/0.46/qiskit.circuit.library.LinearPauliRotations.md new file mode 100644 index 00000000000..791c681ac04 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.LinearPauliRotations.md @@ -0,0 +1,235 @@ +--- +title: LinearPauliRotations +description: API reference for qiskit.circuit.library.LinearPauliRotations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.LinearPauliRotations +--- + +# LinearPauliRotations + + + +`qiskit.circuit.library.LinearPauliRotations(num_state_qubits=None, slope=1, offset=0, basis='Y', name='LinRot')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/linear_pauli_rotations.py "view source code") + +Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") + +Linearly-controlled X, Y or Z rotation. + +For a register of state qubits $|x\rangle$, a target qubit $|0\rangle$ and the basis `'Y'` this circuit acts as: + +```python + q_0: ─────────────────────────■───────── ... ────────────────────── + │ + . + │ +q_(n-1): ─────────────────────────┼───────── ... ───────────■────────── + ┌────────────┐ ┌───────┴───────┐ ┌─────────┴─────────┐ + q_n: ─┤ RY(offset) ├──┤ RY(2^0 slope) ├ ... ┤ RY(2^(n-1) slope) ├ + └────────────┘ └───────────────┘ └───────────────────┘ +``` + +This can for example be used to approximate linear functions, with $a =$ `slope`$/2$ and $b =$ `offset`$/2$ and the basis `'Y'`: + +$$ +|x\rangle |0\rangle \mapsto \cos(ax + b)|x\rangle|0\rangle + \sin(ax + b)|x\rangle |1\rangle +$$ + +Since for small arguments $\sin(x) \approx x$ this operator can be used to approximate linear functions. + +Create a new linear rotation circuit. + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits representing the state $|x\rangle$. +* **slope** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The slope of the controlled rotation. +* **offset** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The offset of the controlled rotation. +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The type of Pauli rotation (‘X’, ‘Y’, ‘Z’). +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### basis + +The kind of Pauli rotation to be used. + +Set the basis to ‘X’, ‘Y’ or ‘Z’ for controlled-X, -Y, or -Z rotations respectively. + +**Returns** + +The kind of Pauli rotation used in controlled rotation. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 163` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +The minimum number of ancilla qubits in the circuit. + +**Returns** + +The minimal number of ancillas required. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits representing the state $|x\rangle$. + +**Returns** + +The number of state qubits. + + + +### offset + +The angle of the single qubit offset rotation on the target qubit. + +Before applying the controlled rotations, a single rotation of angle `offset` is applied to the target qubit. + +**Returns** + +The offset angle. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### slope + +The multiplicative factor in the rotation angle of the controlled rotations. + +The rotation angles are `slope * 2^0`, `slope * 2^1`, … , `slope * 2^(n-1)` where `n` is the number of state qubits. + +**Returns** + +The rotation angle common in all controlled rotations. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCMT.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCMT.md new file mode 100644 index 00000000000..4b1d0dfad2b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCMT.md @@ -0,0 +1,263 @@ +--- +title: MCMT +description: API reference for qiskit.circuit.library.MCMT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCMT +--- + +# MCMT + + + +`qiskit.circuit.library.MCMT(gate, num_ctrl_qubits, num_target_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/mcmt.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +The multi-controlled multi-target gate, for an arbitrary singly controlled target gate. + +For example, the H gate controlled on 3 qubits and acting on 2 target qubit is represented as: + +```python +───■──── + │ +───■──── + │ +───■──── +┌──┴───┐ +┤0 ├ +│ 2-H │ +┤1 ├ +└──────┘ +``` + +This default implementations requires no ancilla qubits, by broadcasting the target gate to the number of target qubits and using Qiskit’s generic control routine to control the broadcasted target on the control qubits. If ancilla qubits are available, a more efficient variant using the so-called V-chain decomposition can be used. This is implemented in [`MCMTVChain`](qiskit.circuit.library.MCMTVChain "qiskit.circuit.library.MCMTVChain"). + +Create a new multi-control multi-target gate. + +**Parameters** + +* **gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate") *| Callable\[\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*,* [*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*,* [*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*],* [*circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*]*) – The gate to be applied controlled on the control qubits and applied to the target qubits. Can be either a Gate or a circuit method. If it is a callable, it will be casted to a Gate. +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of control qubits. +* **num\_target\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of target qubits. + +**Raises** + +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the gate cannot be casted to a controlled gate. +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the number of controls or targets is 0. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 163` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +Return the number of ancillas. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return the controlled version of the MCMT circuit. + +### inverse + + + +`inverse()` + +Return the inverse MCMT circuit, which is itself. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCMTVChain.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCMTVChain.md new file mode 100644 index 00000000000..56c154d4f78 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCMTVChain.md @@ -0,0 +1,279 @@ +--- +title: MCMTVChain +description: API reference for qiskit.circuit.library.MCMTVChain +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCMTVChain +--- + +# MCMTVChain + + + +`qiskit.circuit.library.MCMTVChain(gate, num_ctrl_qubits, num_target_qubits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/mcmt.py "view source code") + +Bases: [`MCMT`](qiskit.circuit.library.MCMT "qiskit.circuit.library.generalized_gates.mcmt.MCMT") + +The MCMT implementation using the CCX V-chain. + +This implementation requires ancillas but is decomposed into a much shallower circuit than the default implementation in [`MCMT`](qiskit.circuit.library.MCMT "qiskit.circuit.library.MCMT"). + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-MCMTVChain-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-MCMTVChain-1.png) + +**Examples:** + +> ```python +> >>> from qiskit.circuit.library import HGate +> >>> MCMTVChain(HGate(), 3, 2).draw() +> ``` +> +> **q\_0: ──■────────────────────────■──** +> +> │ │ +> +> **q\_1: ──■────────────────────────■──** +> +> │ │ +> +> **q\_2: ──┼────■──────────────■────┼──** +> +> │ │ ┌───┐ │ │ +> +> **q\_3: ──┼────┼──┤ H ├───────┼────┼──** +> +> │ │ └─┬─┘┌───┐ │ │ +> +> **q\_4: ──┼────┼────┼──┤ H ├──┼────┼──** +> +> ┌─┴─┐ │ │ └─┬─┘ │ ┌─┴─┐ +> +> **q\_5: ┤ X ├──■────┼────┼────■──┤ X ├** +> +> └───┘┌─┴─┐ │ │ ┌─┴─┐└───┘ +> +> **q\_6: ─────┤ X ├──■────■──┤ X ├─────** +> +> └───┘ └───┘ + +Create a new multi-control multi-target gate. + +**Parameters** + +* **gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate") *| Callable\[\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*,* [*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*,* [*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*],* [*circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*]*) – The gate to be applied controlled on the control qubits and applied to the target qubits. Can be either a Gate or a circuit method. If it is a callable, it will be casted to a Gate. +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of control qubits. +* **num\_target\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of target qubits. + +**Raises** + +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the gate cannot be casted to a controlled gate. +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the number of controls or targets is 0. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 164` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +Return the number of ancilla qubits required. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### inverse + + + +`inverse()` + +Return the inverse MCMT circuit, which is itself. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCPhaseGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCPhaseGate.md new file mode 100644 index 00000000000..9b66055be80 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCPhaseGate.md @@ -0,0 +1,206 @@ +--- +title: MCPhaseGate +description: API reference for qiskit.circuit.library.MCPhaseGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCPhaseGate +--- + +# MCPhaseGate + + + +`qiskit.circuit.library.MCPhaseGate(lam, num_ctrl_qubits, label=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/p.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +Multi-controlled-Phase gate. + +This is a diagonal and symmetric gate that induces a phase on the state of the target qubit, depending on the state of the control qubits. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`mcp()`](qiskit.circuit.QuantumCircuit#mcp "qiskit.circuit.QuantumCircuit.mcp") method. + +**Circuit symbol:** + +```python + q_0: ───■──── + │ + . + │ +q_(n-1): ───■──── + ┌──┴───┐ + q_n: ┤ P(λ) ├ + └──────┘ +``` + + + `CPhaseGate`: The singly-controlled-version of this gate. + + +Create new MCPhase gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.MCPhaseGate.base_class "qiskit.circuit.library.MCPhaseGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Controlled version of this gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted MCU1 gate ($MCU1(\lambda)^{\dagger} = MCU1(-\lambda)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXGate.md new file mode 100644 index 00000000000..e4b71c94a71 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXGate.md @@ -0,0 +1,207 @@ +--- +title: MCXGate +description: API reference for qiskit.circuit.library.MCXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCXGate +--- + +# MCXGate + + + +`qiskit.circuit.library.MCXGate(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.controlledgate.ControlledGate") + +The general, multi-controlled X gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`mcx()`](qiskit.circuit.QuantumCircuit#mcx "qiskit.circuit.QuantumCircuit.mcx") method. + +Create new MCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.MCXGate.base_class "qiskit.circuit.library.MCXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_ancilla\_qubits + +The number of ancilla qubits. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a multi-controlled-X gate with more control lines. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### get\_num\_ancilla\_qubits + + + +`static get_num_ancilla_qubits(num_ctrl_qubits, mode='noancilla')` + +Get the number of required ancilla qubits without instantiating the class. + +This staticmethod might be necessary to check the number of ancillas before creating the gate, or to use the number of ancillas in the initialization. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### inverse + + + +`inverse()` + +Invert this gate. The MCX is its own inverse. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCXGrayCode.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXGrayCode.md new file mode 100644 index 00000000000..4e02d35a033 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXGrayCode.md @@ -0,0 +1,171 @@ +--- +title: MCXGrayCode +description: API reference for qiskit.circuit.library.MCXGrayCode +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCXGrayCode +--- + +# MCXGrayCode + + + +`qiskit.circuit.library.MCXGrayCode(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.standard_gates.x.MCXGate") + +Implement the multi-controlled X gate using the Gray code. + +This delegates the implementation to the MCU1 gate, since $X = H \cdot U1(\pi) \cdot H$. + +Create new MCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.MCXGrayCode.base_class "qiskit.circuit.library.MCXGrayCode.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_ancilla\_qubits + +The number of ancilla qubits. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Invert this gate. The MCX is its own inverse. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCXRecursive.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXRecursive.md new file mode 100644 index 00000000000..f4aaa5c9e3f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXRecursive.md @@ -0,0 +1,179 @@ +--- +title: MCXRecursive +description: API reference for qiskit.circuit.library.MCXRecursive +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCXRecursive +--- + +# MCXRecursive + + + +`qiskit.circuit.library.MCXRecursive(num_ctrl_qubits=None, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.standard_gates.x.MCXGate") + +Implement the multi-controlled X gate using recursion. + +Using a single ancilla qubit, the multi-controlled X gate is recursively split onto four sub-registers. This is done until we reach the 3- or 4-controlled X gate since for these we have a concrete implementation that do not require ancillas. + +Create new MCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.MCXRecursive.base_class "qiskit.circuit.library.MCXRecursive.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_ancilla\_qubits + +The number of ancilla qubits. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### get\_num\_ancilla\_qubits + + + +`static get_num_ancilla_qubits(num_ctrl_qubits, mode='recursion')` + +Get the number of required ancilla qubits. + +### inverse + + + +`inverse()` + +Invert this gate. The MCX is its own inverse. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MCXVChain.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXVChain.md new file mode 100644 index 00000000000..ad8646ee796 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MCXVChain.md @@ -0,0 +1,177 @@ +--- +title: MCXVChain +description: API reference for qiskit.circuit.library.MCXVChain +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MCXVChain +--- + +# MCXVChain + + + +`qiskit.circuit.library.MCXVChain(num_ctrl_qubits=None, dirty_ancillas=False, label=None, ctrl_state=None, *, duration=None, unit='dt', _base_label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.standard_gates.x.MCXGate") + +Implement the multi-controlled X gate using a V-chain of CX gates. + +Create new MCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.MCXVChain.base_class "qiskit.circuit.library.MCXVChain.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### ctrl\_state + +Return the control state of the gate as a decimal integer. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. If the gate has open controls, as determined from self.ctrl\_state, the returned definition is conjugated with X without changing the internal \_definition. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Get name of gate. If the gate has open controls the gate name will become: + +> \ + +where \ is the gate name for the default case of closed control qubits and \ is the integer value of the control state for the gate. + + + +### num\_ancilla\_qubits + +The number of ancilla qubits. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_ctrl\_qubits + +Get number of control qubits. + +**Returns** + +The number of control qubits for the gate. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +Get parameters from base\_gate. + +**Returns** + +List of gate parameters. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Controlled gate does not define a base gate + + + +### unit + +Get the time unit of duration. + +## Methods + +### get\_num\_ancilla\_qubits + + + +`static get_num_ancilla_qubits(num_ctrl_qubits, mode='v-chain')` + +Get the number of required ancilla qubits. + +### inverse + + + +`inverse()` + +Invert this gate. The MCX is its own inverse. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.MSGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.MSGate.md new file mode 100644 index 00000000000..7da50cb3367 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.MSGate.md @@ -0,0 +1,123 @@ +--- +title: MSGate +description: API reference for qiskit.circuit.library.MSGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.MSGate +--- + +# MSGate + + + +`qiskit.circuit.library.MSGate(num_qubits, theta, label=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/gms.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +MSGate has been deprecated. Please use `GMS` in `qiskit.circuit.generalized_gates` instead. + +Global Mølmer–Sørensen gate. + +The Mølmer–Sørensen gate is native to ion-trap systems. The global MS can be applied to multiple ions to entangle multiple qubits simultaneously. + +In the two-qubit case, this is equivalent to an XX(theta) interaction, and is thus reduced to the RXXGate. + +Create new MS gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.MSGate.base_class "qiskit.circuit.library.MSGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Measure.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Measure.md new file mode 100644 index 00000000000..bc7e942ea5c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Measure.md @@ -0,0 +1,316 @@ +--- +title: Measure +description: API reference for qiskit.circuit.library.Measure +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Measure +--- + +# Measure + + + +`qiskit.circuit.library.Measure(label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/measure.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Quantum measurement in the computational basis. + +Create new measurement instruction. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.Measure.base_class "qiskit.circuit.library.Measure.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.NLocal.md b/docs/api/qiskit/0.46/qiskit.circuit.library.NLocal.md new file mode 100644 index 00000000000..fc3277f1b2f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.NLocal.md @@ -0,0 +1,462 @@ +--- +title: NLocal +description: API reference for qiskit.circuit.library.NLocal +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.NLocal +--- + +# NLocal + + + +`qiskit.circuit.library.NLocal(num_qubits=None, rotation_blocks=None, entanglement_blocks=None, entanglement=None, reps=1, insert_barriers=False, parameter_prefix='θ', overwrite_block_parameters=True, skip_final_rotation_layer=False, skip_unentangled_qubits=False, initial_state=None, name='nlocal', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/n_local.py "view source code") + +Bases: `BlueprintCircuit` + +The n-local circuit class. + +The structure of the n-local circuit are alternating rotation and entanglement layers. In both layers, parameterized circuit-blocks act on the circuit in a defined way. In the rotation layer, the blocks are applied stacked on top of each other, while in the entanglement layer according to the `entanglement` strategy. The circuit blocks can have arbitrary sizes (smaller equal to the number of qubits in the circuit). Each layer is repeated `reps` times, and by default a final rotation layer is appended. + +For instance, a rotation block on 2 qubits and an entanglement block on 4 qubits using `'linear'` entanglement yields the following circuit. + +```python +┌──────┐ ░ ┌──────┐ ░ ┌──────┐ +┤0 ├─░─┤0 ├──────────────── ... ─░─┤0 ├ +│ Rot │ ░ │ │┌──────┐ ░ │ Rot │ +┤1 ├─░─┤1 ├┤0 ├──────── ... ─░─┤1 ├ +├──────┤ ░ │ Ent ││ │┌──────┐ ░ ├──────┤ +┤0 ├─░─┤2 ├┤1 ├┤0 ├ ... ─░─┤0 ├ +│ Rot │ ░ │ ││ Ent ││ │ ░ │ Rot │ +┤1 ├─░─┤3 ├┤2 ├┤1 ├ ... ─░─┤1 ├ +├──────┤ ░ └──────┘│ ││ Ent │ ░ ├──────┤ +┤0 ├─░─────────┤3 ├┤2 ├ ... ─░─┤0 ├ +│ Rot │ ░ └──────┘│ │ ░ │ Rot │ +┤1 ├─░─────────────────┤3 ├ ... ─░─┤1 ├ +└──────┘ ░ └──────┘ ░ └──────┘ + +| | ++---------------------------------+ + repeated reps times +``` + +If specified, barriers can be inserted in between every block. If an initial state object is provided, it is added in front of the NLocal. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits of the circuit. +* **rotation\_blocks** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] |* [*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*] | None*) – The blocks used in the rotation layers. If multiple are passed, these will be applied one after another (like new sub-layers). +* **entanglement\_blocks** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] |* [*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*] | None*) – The blocks used in the entanglement layers. If multiple are passed, these will be applied one after another. To use different entanglements for the sub-layers, see [`get_entangler_map()`](#qiskit.circuit.library.NLocal.get_entangler_map "qiskit.circuit.library.NLocal.get_entangler_map"). +* **entanglement** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – The indices specifying on which qubits the input blocks act. If `None`, the entanglement blocks are applied at the top of the circuit. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Specifies how often the rotation blocks and entanglement blocks are repeated. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, barriers are inserted in between each layer. If `False`, no barriers are inserted. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The prefix used if default parameters are generated. +* **overwrite\_block\_parameters** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*]]*) – If the parameters in the added blocks should be overwritten. If `False`, the parameters in the blocks are not changed. +* **skip\_final\_rotation\_layer** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether a final rotation layer is added to the circuit. +* **skip\_unentangled\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, the rotation gates act only on qubits that are entangled. If `False`, the rotation gates act on all qubits. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object which can be used to describe an initial state prepended to the NLocal circuit. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The name of the circuit. +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `reps` parameter is less than or equal to 0. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `reps` parameter is not an int value. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see [`get_entangler_map()`](#qiskit.circuit.library.NLocal.get_entangler_map "qiskit.circuit.library.NLocal.get_entangler_map") for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 165` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + +## Methods + +### add\_layer + + + +`add_layer(other, entanglement=None, front=False)` + +Append another layer to the NLocal. + +**Parameters** + +* **other** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – The layer to compose, can be another NLocal, an Instruction or Gate, or a QuantumCircuit. +* **entanglement** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – The entanglement or qubit indices. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, `other` is appended to the front, else to the back. + +**Returns** + +self, such that chained composes are possible. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If other is not compatible, i.e. is no Instruction and does not have a to\_instruction method. + +**Return type** + +[NLocal](#qiskit.circuit.library.NLocal "qiskit.circuit.library.NLocal") + +### assign\_parameters + + + +`assign_parameters(parameters, inplace=False, **kwargs)` + +Assign parameters to the n-local circuit. + +This method also supports passing a list instead of a dictionary. If a list is passed, the list must have the same length as the number of unbound parameters in the circuit. The parameters are assigned in the order of the parameters in [`ordered_parameters()`](#qiskit.circuit.library.NLocal.ordered_parameters "qiskit.circuit.library.NLocal.ordered_parameters"). + +**Returns** + +A copy of the NLocal circuit with the specified parameters. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the parameters are given as list and do not match the number of parameters. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") | None + +### get\_entangler\_map + + + +`get_entangler_map(rep_num, block_num, num_block_qubits)` + +Get the entangler map for in the repetition `rep_num` and the block `block_num`. + +The entangler map for the current block is derived from the value of `self.entanglement`. Below the different cases are listed, where `i` and `j` denote the repetition number and the block number, respectively, and `n` the number of qubits in the block. + +| entanglement type | entangler map | +| -------------------------------- | -------------------------------------------------- | +| `None` | `[[0, ..., n - 1]]` | +| `str` (e.g `'full'`) | the specified connectivity on `n` qubits | +| `List[int]` | \[`entanglement`] | +| `List[List[int]]` | `entanglement` | +| `List[List[List[int]]]` | `entanglement[i]` | +| `List[List[List[List[int]]]]` | `entanglement[i][j]` | +| `List[str]` | the connectivity specified in `entanglement[i]` | +| `List[List[str]]` | the connectivity specified in `entanglement[i][j]` | +| `Callable[int, str]` | same as `List[str]` | +| `Callable[int, List[List[int]]]` | same as `List[List[List[int]]]` | + +Note that all indices are to be taken modulo the length of the array they act on, i.e. no out-of-bounds index error will be raised but we re-iterate from the beginning of the list. + +**Parameters** + +* **rep\_num** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The current repetition we are in. +* **block\_num** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The block number within the entanglement layers. +* **num\_block\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits in the block. + +**Returns** + +The entangler map for the current block in the current repetition. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the value of `entanglement` could not be cast to a corresponding entangler map. + +**Return type** + +[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] + +### get\_unentangled\_qubits + + + +`get_unentangled_qubits()` + +Get the indices of unentangled qubits in a set. + +**Returns** + +The unentangled qubits. + +**Return type** + +[set](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### print\_settings + + + +`print_settings()` + +Returns information about the setting. + +**Returns** + +The class name and the attributes/parameters of the instance as `str`. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.OR.md b/docs/api/qiskit/0.46/qiskit.circuit.library.OR.md new file mode 100644 index 00000000000..1dd502a2a2f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.OR.md @@ -0,0 +1,227 @@ +--- +title: OR +description: API reference for qiskit.circuit.library.OR +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.OR +--- + +# OR + + + +`qiskit.circuit.library.OR(num_variable_qubits, flags=None, mcx_mode='noancilla')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/boolean_logic/quantum_or.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +A circuit implementing the logical OR operation on a number of qubits. + +For the OR operation the state $|1\rangle$ is interpreted as `True`. The result qubit is flipped, if the state of any variable qubit is `True`. The OR is implemented using a multi-open-controlled X gate (i.e. flips if the state is $|0\rangle$) and applying an X gate on the result qubit. Using a list of flags, qubits can be skipped or negated. + +The OR gate without special flags: + +![../\_images/qiskit-circuit-library-OR-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-OR-1.png) + +Using flags we can negate qubits or skip them. For instance, if we have 5 qubits and want to return `True` if the first qubit is `False` or one of the last two are `True` we use the flags `[-1, 0, 0, 1, 1]`. + +![../\_images/qiskit-circuit-library-OR-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-OR-2.png) + +Create a new logical OR circuit. + +**Parameters** + +* **num\_variable\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The qubits of which the OR is computed. The result will be written into an additional result qubit. +* **flags** (*Optional\[List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – A list of +1/0/-1 marking negations or omissions of qubits. +* **mcx\_mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The mode to be used to implement the multi-controlled X gate. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 168` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PauliEvolutionGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliEvolutionGate.md new file mode 100644 index 00000000000..985bd6ab6ee --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliEvolutionGate.md @@ -0,0 +1,191 @@ +--- +title: PauliEvolutionGate +description: API reference for qiskit.circuit.library.PauliEvolutionGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PauliEvolutionGate +--- + +# PauliEvolutionGate + + + +`qiskit.circuit.library.PauliEvolutionGate(operator, time=1.0, label=None, synthesis=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/pauli_evolution.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Time-evolution of an operator consisting of Paulis. + +For an operator $H$ consisting of Pauli terms and (real) evolution time $t$ this gate implements + +$$ +U(t) = e^{-itH}. +$$ + +This gate serves as a high-level definition of the evolution and can be synthesized into a circuit using different algorithms. + +The evolution gates are related to the Pauli rotation gates by a factor of 2. For example the time evolution of the Pauli $X$ operator is connected to the Pauli $X$ rotation $R_X$ by + +$$ +U(t) = e^{-itX} = R_X(2t). +$$ + +**Examples:** + +```python +from qiskit.circuit import QuantumCircuit +from qiskit.circuit.library import PauliEvolutionGate +from qiskit.opflow import I, Z, X + +# build the evolution gate +operator = (Z ^ Z) - 0.1 * (X ^ I) +evo = PauliEvolutionGate(operator, time=0.2) + +# plug it into a circuit +circuit = QuantumCircuit(2) +circuit.append(evo, range(2)) +print(circuit.draw()) +``` + +The above will print (note that the `-0.1` coefficient is not printed!): + +```python + ┌──────────────────────────┐ +q_0: ┤0 ├ + │ exp(-it (ZZ + XI))(0.2) │ +q_1: ┤1 ├ + └──────────────────────────┘ +``` + +**References:** + +\[1] G. Li et al. Paulihedral: A Generalized Block-Wise Compiler Optimization Framework For Quantum Simulation Kernels (2021). \[[arXiv:2109.03371](https://arxiv.org/abs/2109.03371)] + +**Parameters** + +* **operator** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *|*[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.PauliOp") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The operator to evolve. Can also be provided as list of non-commuting operators where the elements are sums of commuting operators. For example: `[XY + YX, ZZ + ZI + IZ, YY]`. +* **time** (*Union\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – The evolution time. +* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – A label for the gate to display in visualizations. Per default, the label is set to `exp(-it )` where `` is the sum of the Paulis. Note that the label does not include any coefficients of the Paulis. See the class docstring for an example. +* **synthesis** (*Optional\[*[*EvolutionSynthesis*](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis")*]*) – A synthesis strategy. If None, the default synthesis is the Lie-Trotter product formula with a single repetition. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.PauliEvolutionGate.base_class "qiskit.circuit.library.PauliEvolutionGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### time + +Return the evolution time as stored in the gate parameters. + +**Returns** + +The evolution time. + + + +### unit + +Get the time unit of duration. + +## Methods + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Gate parameters should be int, float, or ParameterExpression + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PauliFeatureMap.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliFeatureMap.md new file mode 100644 index 00000000000..8ee9fc54600 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliFeatureMap.md @@ -0,0 +1,418 @@ +--- +title: PauliFeatureMap +description: API reference for qiskit.circuit.library.PauliFeatureMap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PauliFeatureMap +--- + +# PauliFeatureMap + + + +`qiskit.circuit.library.PauliFeatureMap(feature_dimension=None, reps=2, entanglement='full', alpha=2.0, paulis=None, data_map_func=None, parameter_prefix='x', insert_barriers=False, name='PauliFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/data_preparation/pauli_feature_map.py "view source code") + +Bases: [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.n_local.n_local.NLocal") + +The Pauli Expansion circuit. + +The Pauli Expansion circuit is a data encoding circuit that transforms input data $\vec{x} \in \mathbb{R}^n$, where n is the `feature_dimension`, as + +$$ +U_{\Phi(\vec{x})}=\exp\left(i\sum_{S \in \mathcal{I}} +\phi_S(\vec{x})\prod_{i\in S} P_i\right). +$$ + +Here, $S$ is a set of qubit indices that describes the connections in the feature map, $\mathcal{I}$ is a set containing all these index sets, and $P_i \in \{I, X, Y, Z\}$. Per default the data-mapping $\phi_S$ is + +$$ +\phi_S(\vec{x}) = \begin{cases} + x_i \text{ if } S = \{i\} \\ + \prod_{j \in S} (\pi - x_j) \text{ if } |S| > 1 + \end{cases}. +$$ + +The possible connections can be set using the `entanglement` and `paulis` arguments. For example, for single-qubit $Z$ rotations and two-qubit $YY$ interactions between all qubit pairs, we can set: + +```python +feature_map = PauliFeatureMap(..., paulis=["Z", "YY"], entanglement="full") +``` + +which will produce blocks of the form + +```python +┌───┐┌──────────────┐┌──────────┐ ┌───────────┐ +┤ H ├┤ U1(2.0*x[0]) ├┤ RX(pi/2) ├──■───────────────────────────────────────■──┤ RX(-pi/2) ├ +├───┤├──────────────┤├──────────┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐├───────────┤ +┤ H ├┤ U1(2.0*x[1]) ├┤ RX(pi/2) ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ RX(-pi/2) ├ +└───┘└──────────────┘└──────────┘└───┘└─────────────────────────────────┘└───┘└───────────┘ +``` + +The circuit contains `reps` repetitions of this transformation. + +Please refer to [`ZFeatureMap`](qiskit.circuit.library.ZFeatureMap "qiskit.circuit.library.ZFeatureMap") for the case of single-qubit Pauli-$Z$ rotations and to [`ZZFeatureMap`](qiskit.circuit.library.ZZFeatureMap "qiskit.circuit.library.ZZFeatureMap") for the single- and two-qubit Pauli-$Z$ rotations. + +**Examples** + +```python +>>> prep = PauliFeatureMap(2, reps=1, paulis=['ZZ']) +>>> print(prep) + ┌───┐ +q_0: ┤ H ├──■───────────────────────────────────────■── + ├───┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐ +q_1: ┤ H ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├ + └───┘└───┘└─────────────────────────────────┘└───┘ +``` + +```python +>>> prep = PauliFeatureMap(2, reps=1, paulis=['Z', 'XX']) +>>> print(prep) + ┌───┐┌──────────────┐┌───┐ ┌───┐ +q_0: ┤ H ├┤ U1(2.0*x[0]) ├┤ H ├──■───────────────────────────────────────■──┤ H ├ + ├───┤├──────────────┤├───┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐├───┤ +q_1: ┤ H ├┤ U1(2.0*x[1]) ├┤ H ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├┤ H ├ + └───┘└──────────────┘└───┘└───┘└─────────────────────────────────┘└───┘└───┘ +``` + +```python +>>> prep = PauliFeatureMap(2, reps=1, paulis=['ZY']) +>>> print(prep) + ┌───┐┌──────────┐ ┌───────────┐ +q_0: ┤ H ├┤ RX(pi/2) ├──■───────────────────────────────────────■──┤ RX(-pi/2) ├ + ├───┤└──────────┘┌─┴─┐┌─────────────────────────────────┐┌─┴─┐└───────────┘ +q_1: ┤ H ├────────────┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├───────────── + └───┘ └───┘└─────────────────────────────────┘└───┘ +``` + +```python +>>> from qiskit.circuit.library import EfficientSU2 +>>> prep = PauliFeatureMap(3, reps=3, paulis=['Z', 'YY', 'ZXZ']) +>>> wavefunction = EfficientSU2(3) +>>> classifier = prep.compose(wavefunction +>>> classifier.num_parameters +27 +>>> classifier.count_ops() +OrderedDict([('cx', 39), ('rx', 36), ('u1', 21), ('h', 15), ('ry', 12), ('rz', 12)]) +``` + +References: + +\[1] Havlicek et al. Supervised learning with quantum enhanced feature spaces, [Nature 567, 209-212 (2019)](https://www.nature.com/articles/s41586-019-0980-2). + +Create a new Pauli expansion circuit. + +**Parameters** + +* **feature\_dimension** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Number of qubits in the circuit. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of repeated circuits. +* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] |* [*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Specifies the entanglement structure. Refer to [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.NLocal") for detail. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The Pauli rotation factor, multiplicative to the pauli rotations +* **paulis** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – A list of strings for to-be-used paulis. If None are provided, `['Z', 'ZZ']` will be used. +* **data\_map\_func** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A mapping function for data x which can be supplied to override the default mapping from `self_product()`. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The prefix used if default parameters are generated. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted in between the evolution instructions and hadamard layers. + +## Attributes + + + +### alpha + +The Pauli rotation factor (alpha). + +**Returns** + +The Pauli rotation factor. + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### feature\_dimension + +Returns the feature dimension (which is equal to the number of qubits). + +**Returns** + +The feature dimension of this feature map. + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 173` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of distinct parameters. + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### paulis + +The Pauli strings used in the entanglement of the qubits. + +**Returns** + +The Pauli strings as list. + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + +## Methods + +### pauli\_block + + + +`pauli_block(pauli_string)` + +Get the Pauli block for the feature map circuit. + +### pauli\_evolution + + + +`pauli_evolution(pauli_string, time)` + +Get the evolution block for the given pauli string. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PauliGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliGate.md new file mode 100644 index 00000000000..81b9602d8bc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliGate.md @@ -0,0 +1,148 @@ +--- +title: PauliGate +description: API reference for qiskit.circuit.library.PauliGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PauliGate +--- + +# PauliGate + + + +`qiskit.circuit.library.PauliGate(label)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/pauli.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A multi-qubit Pauli gate. + +This gate exists for optimization purposes for the quantum statevector simulation, since applying multiple pauli gates to different qubits at once can be done via a single pass on the statevector. + +The functionality is equivalent to applying the pauli gates sequentially using standard Qiskit gates. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`pauli()`](qiskit.circuit.QuantumCircuit#pauli "qiskit.circuit.QuantumCircuit.pauli") method. + +Create a new gate. + +**Parameters** + +* **name** – The Qobj name of the gate. +* **num\_qubits** – The number of qubits the gate acts on. +* **params** – A list of parameters. +* **label** – An optional label for the gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.PauliGate.base_class "qiskit.circuit.library.PauliGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted pauli gate (itself). + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Gate parameters should be int, float, or ParameterExpression + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PauliTwoDesign.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliTwoDesign.md new file mode 100644 index 00000000000..282be122251 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PauliTwoDesign.md @@ -0,0 +1,329 @@ +--- +title: PauliTwoDesign +description: API reference for qiskit.circuit.library.PauliTwoDesign +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PauliTwoDesign +--- + +# PauliTwoDesign + + + +`qiskit.circuit.library.PauliTwoDesign(num_qubits=None, reps=3, seed=None, insert_barriers=False, name='PauliTwoDesign')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/pauli_two_design.py "view source code") + +Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") + +The Pauli Two-Design ansatz. + +This class implements a particular form of a 2-design circuit \[1], which is frequently studied in quantum machine learning literature, such as e.g. the investigating of Barren plateaus in variational algorithms \[2]. + +The circuit consists of alternating rotation and entanglement layers with an initial layer of $\sqrt{H} = RY(\pi/4)$ gates. The rotation layers contain single qubit Pauli rotations, where the axis is chosen uniformly at random to be X, Y or Z. The entanglement layers is compromised of pairwise CZ gates with a total depth of 2. + +For instance, the circuit could look like this (but note that choosing a different seed yields different Pauli rotations). + +```python + ┌─────────┐┌──────────┐ ░ ┌──────────┐ ░ ┌──────────┐ +q_0: ┤ RY(π/4) ├┤ RZ(θ[0]) ├─■─────░─┤ RY(θ[4]) ├─■─────░──┤ RZ(θ[8]) ├ + ├─────────┤├──────────┤ │ ░ ├──────────┤ │ ░ ├──────────┤ +q_1: ┤ RY(π/4) ├┤ RZ(θ[1]) ├─■──■──░─┤ RY(θ[5]) ├─■──■──░──┤ RX(θ[9]) ├ + ├─────────┤├──────────┤ │ ░ ├──────────┤ │ ░ ┌┴──────────┤ +q_2: ┤ RY(π/4) ├┤ RX(θ[2]) ├─■──■──░─┤ RY(θ[6]) ├─■──■──░─┤ RX(θ[10]) ├ + ├─────────┤├──────────┤ │ ░ ├──────────┤ │ ░ ├───────────┤ +q_3: ┤ RY(π/4) ├┤ RZ(θ[3]) ├─■─────░─┤ RX(θ[7]) ├─■─────░─┤ RY(θ[11]) ├ + └─────────┘└──────────┘ ░ └──────────┘ ░ └───────────┘ +``` + +**Examples** + +```python +from qiskit.circuit.library import PauliTwoDesign +circuit = PauliTwoDesign(4, reps=2, seed=5, insert_barriers=True) +circuit.draw('mpl') +``` + +![../\_images/qiskit-circuit-library-PauliTwoDesign-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-PauliTwoDesign-1.png) + +**References** + +**\[1]: Nakata et al., Unitary 2-designs from random X- and Z-diagonal unitaries.** + +[arXiv:1502.07514](https://arxiv.org/pdf/1502.07514.pdf) + +**\[2]: McClean et al., Barren plateaus in quantum neural network training landscapes.** + +[arXiv:1803.11173](https://arxiv.org/pdf/1803.11173.pdf) + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits of the Pauli Two-Design circuit. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Specifies how often a block consisting of a rotation layer and entanglement layer is repeated. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The seed for randomly choosing the axes of the Pauli rotations. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, barriers are inserted in between each layer. If `False`, no barriers are inserted. Defaults to `False`. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 174` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +Return the number of settable parameters. + +**Returns** + +The number of possibly distinct parameters. + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Permutation.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Permutation.md new file mode 100644 index 00000000000..67683df9d9f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Permutation.md @@ -0,0 +1,229 @@ +--- +title: Permutation +description: API reference for qiskit.circuit.library.Permutation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Permutation +--- + +# Permutation + + + +`qiskit.circuit.library.Permutation(num_qubits, pattern=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/permutation.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +An n\_qubit circuit that permutes qubits. + +Return an n\_qubit permutation circuit implemented using SWAPs. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – circuit width. +* **pattern** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | np.ndarray | None*) – permutation pattern, describing which qubits occupy the positions 0, 1, 2, etc. after applying the permutation, that is `pattern[k] = m` when the permutation maps qubit `m` to position `k`. As an example, the pattern `[2, 4, 3, 0, 1]` means that qubit `2` goes to position `0`, qubit `4` goes to the position `1`, etc. The pattern can also be `None`, in which case a random permutation over `num_qubits` is created. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – random seed in case a random permutation is requested. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if permutation pattern is malformed. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-Permutation-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-Permutation-1.png) + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-Permutation-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-Permutation-2.png) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 192` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PermutationGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PermutationGate.md new file mode 100644 index 00000000000..469398a0091 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PermutationGate.md @@ -0,0 +1,157 @@ +--- +title: PermutationGate +description: API reference for qiskit.circuit.library.PermutationGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PermutationGate +--- + +# PermutationGate + + + +`qiskit.circuit.library.PermutationGate(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/permutation.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A gate that permutes qubits. + +Return a permutation gate. + +**Parameters** + +**pattern** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – permutation pattern, describing which qubits occupy the positions 0, 1, 2, etc. after applying the permutation, that is `pattern[k] = m` when the permutation maps qubit `m` to position `k`. As an example, the pattern `[2, 4, 3, 0, 1]` means that qubit `2` goes to position `0`, qubit `4` goes to the position `1`, etc. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if permutation pattern is malformed. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-PermutationGate-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-PermutationGate-1.png) + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-PermutationGate-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-PermutationGate-2.png) + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.PermutationGate.base_class "qiskit.circuit.library.PermutationGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### pattern + +Returns the permutation pattern defining this permutation. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Returns the inverse of the permutation. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Parameter validation. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseEstimation.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseEstimation.md new file mode 100644 index 00000000000..ee66766b1eb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseEstimation.md @@ -0,0 +1,246 @@ +--- +title: PhaseEstimation +description: API reference for qiskit.circuit.library.PhaseEstimation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PhaseEstimation +--- + +# PhaseEstimation + + + +`qiskit.circuit.library.PhaseEstimation(num_evaluation_qubits, unitary, iqft=None, name='QPE')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/phase_estimation.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Phase Estimation circuit. + +In the Quantum Phase Estimation (QPE) algorithm \[1, 2, 3], the Phase Estimation circuit is used to estimate the phase $\phi$ of an eigenvalue $e^{2\pi i\phi}$ of a unitary operator $U$, provided with the corresponding eigenstate $|\psi\rangle$. That is + +$$ +U|\psi\rangle = e^{2\pi i\phi} |\psi\rangle +$$ + +This estimation (and thereby this circuit) is a central routine to several well-known algorithms, such as Shor’s algorithm or Quantum Amplitude Estimation. + +**References:** + +**\[1]: Kitaev, A. Y. (1995). Quantum measurements and the Abelian Stabilizer Problem. 1–22.** + +[quant-ph/9511026](http://arxiv.org/abs/quant-ph/9511026) + +**\[2]: Michael A. Nielsen and Isaac L. Chuang. 2011.** + +Quantum Computation and Quantum Information: 10th Anniversary Edition (10th ed.). Cambridge University Press, New York, NY, USA. + +**\[3]: Qiskit** + +[textbook](https://github.com/Qiskit/textbook/blob/main/notebooks/ch-algorithms/quantum-phase-estimation.ipynb) + +**Parameters** + +* **num\_evaluation\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of evaluation qubits. +* **unitary** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The unitary operation $U$ which will be repeated and controlled. +* **iqft** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *| None*) – A inverse Quantum Fourier Transform, per default the inverse of [`QFT`](qiskit.circuit.library.QFT "qiskit.circuit.library.QFT") is used. Note that the QFT should not include the usual swaps! +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + + + The inverse QFT should not include a swap of the qubit order. + + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-PhaseEstimation-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-PhaseEstimation-1.png) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 246` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseGate.md new file mode 100644 index 00000000000..0d5ed6963c0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseGate.md @@ -0,0 +1,203 @@ +--- +title: PhaseGate +description: API reference for qiskit.circuit.library.PhaseGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PhaseGate +--- + +# PhaseGate + + + +`qiskit.circuit.library.PhaseGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/p.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit rotation about the Z axis. + +This is a diagonal gate. It can be implemented virtually in hardware via framechanges (i.e. at zero error and duration). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`p()`](qiskit.circuit.QuantumCircuit#p "qiskit.circuit.QuantumCircuit.p") method. + +**Circuit symbol:** + +```python + ┌──────┐ +q_0: ┤ P(λ) ├ + └──────┘ +``` + +**Matrix Representation:** + +$$ +P(\lambda) = + \begin{pmatrix} + 1 & 0 \\ + 0 & e^{i\lambda} + \end{pmatrix} +$$ + +**Examples:** + +> $$ +> P(\lambda = \pi) = Z +> $$ +> +> $$ +> P(\lambda = \pi/2) = S +> $$ +> +> $$ +> P(\lambda = \pi/4) = T +> $$ + + + `RZGate`: This gate is equivalent to RZ up to a phase factor. + + > $$ + > P(\lambda) = e^{i{\lambda}/2} RZ(\lambda) + > $$ + + Reference for virtual Z gate implementation: [1612.00858](https://arxiv.org/abs/1612.00858) + + +Create new Phase gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.PhaseGate.base_class "qiskit.circuit.library.PhaseGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-Phase gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted Phase gate ($Phase(\lambda)^{\dagger} = Phase(-\lambda)$) + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseOracle.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseOracle.md new file mode 100644 index 00000000000..417bd3cacce --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PhaseOracle.md @@ -0,0 +1,283 @@ +--- +title: PhaseOracle +description: API reference for qiskit.circuit.library.PhaseOracle +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PhaseOracle +--- + +# PhaseOracle + + + +`qiskit.circuit.library.PhaseOracle(expression, synthesizer=None, var_order=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/phase_oracle.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Phase Oracle. + +The Phase Oracle object constructs circuits for any arbitrary input logical expressions. A logical expression is composed of logical operators & (AND), | (OR), \~ (NOT), and ^ (XOR). as well as symbols for literals (variables). For example, ‘a & b’, and (v0 | \~v1) & (\~v2 & v3) are both valid string representation of boolean logical expressions. + +For convenience, this oracle, in addition to parsing arbitrary logical expressions, also supports input strings in the [DIMACS CNF format](http://www.satcompetition.org/2009/format-benchmarks2009.html), which is the standard format for specifying SATisfiability (SAT) problem instances in [Conjunctive Normal Form (CNF)](https://en.wikipedia.org/wiki/Conjunctive_normal_form), which is a conjunction of one or more clauses, where a clause is a disjunction of one or more literals. See `qiskit.circuit.library.phase_oracle.PhaseOracle.from_dimacs_file()`. + +From 16 variables on, possible performance issues should be expected when using the default synthesizer. + +Creates a PhaseOracle object + +**Parameters** + +* **expression** (*Union\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, ClassicalElement]*) – A Python-like boolean expression. +* **synthesizer** (*Optional\[Callable\[\[*[*BooleanExpression*](qiskit.circuit.classicalfunction.BooleanExpression "qiskit.circuit.classicalfunction.BooleanExpression")*],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]]*) – Optional. A function to convert a BooleanExpression into a QuantumCircuit If None is provided, Tweedledum’s pkrm\_synth with phase\_esop will be used. +* **var\_order** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list with the order in which variables will be created. (default: by appearance) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 248` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### evaluate\_bitstring + + + +`evaluate_bitstring(bitstring)` + +Evaluate the oracle on a bitstring. This evaluation is done classically without any quantum circuit. + +**Parameters** + +**bitstring** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The bitstring for which to evaluate. The input bitstring is expected to be in little-endian order. + +**Returns** + +True if the bitstring is a good state, False otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### from\_dimacs\_file + + + +`classmethod from_dimacs_file(filename)` + +Create a PhaseOracle from the string in the DIMACS format. + +It is possible to build a PhaseOracle from a file in [DIMACS CNF format](http://www.satcompetition.org/2009/format-benchmarks2009.html), which is the standard format for specifying SATisfiability (SAT) problem instances in [Conjunctive Normal Form (CNF)](https://en.wikipedia.org/wiki/Conjunctive_normal_form), which is a conjunction of one or more clauses, where a clause is a disjunction of one or more literals. + +The following is an example of a CNF expressed in the DIMACS format: + +```python +c DIMACS CNF file with 3 satisfying assignments: 1 -2 3, -1 -2 -3, 1 2 -3. +p cnf 3 5 +-1 -2 -3 0 +1 -2 3 0 +1 2 -3 0 +1 -2 -3 0 +-1 2 3 0 +``` + +The first line, following the c character, is a comment. The second line specifies that the CNF is over three boolean variables — let us call them $x_1, x_2, x_3$, and contains five clauses. The five clauses, listed afterwards, are implicitly joined by the logical AND operator, $\land$, while the variables in each clause, represented by their indices, are implicitly disjoined by the logical OR operator, $lor$. The $-$ symbol preceding a boolean variable index corresponds to the logical NOT operator, $lnot$. Character 0 (zero) marks the end of each clause. Essentially, the code above corresponds to the following CNF: + +$(\lnot x_1 \lor \lnot x_2 \lor \lnot x_3) \land (x_1 \lor \lnot x_2 \lor x_3) \land (x_1 \lor x_2 \lor \lnot x_3) \land (x_1 \lor \lnot x_2 \lor \lnot x_3) \land (\lnot x_1 \lor x_2 \lor x_3)$. + +**Parameters** + +**filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A file in DIMACS format. + +**Returns** + +A quantum circuit with a phase oracle. + +**Return type** + +[PhaseOracle](#qiskit.circuit.library.PhaseOracle "qiskit.circuit.library.PhaseOracle") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseChebyshev.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseChebyshev.md new file mode 100644 index 00000000000..67e2a5ceb11 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseChebyshev.md @@ -0,0 +1,241 @@ +--- +title: PiecewiseChebyshev +description: API reference for qiskit.circuit.library.PiecewiseChebyshev +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PiecewiseChebyshev +--- + +# PiecewiseChebyshev + + + +`qiskit.circuit.library.PiecewiseChebyshev(f_x, degree=None, breakpoints=None, num_state_qubits=None, name='pw_cheb')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/piecewise_chebyshev.py "view source code") + +Bases: `BlueprintCircuit` + +Piecewise Chebyshev approximation to an input function. + +For a given function $f(x)$ and degree $d$, this class implements a piecewise polynomial Chebyshev approximation on $n$ qubits to $f(x)$ on the given intervals. All the polynomials in the approximation are of degree $d$. + +The values of the parameters are calculated according to \[1] and see \[2] for a more detailed explanation of the circuit construction and how it acts on the qubits. + +**Examples** + +```python +import numpy as np +from qiskit import QuantumCircuit +from qiskit.circuit.library.arithmetic.piecewise_chebyshev import PiecewiseChebyshev +f_x, degree, breakpoints, num_state_qubits = lambda x: np.arcsin(1 / x), 2, [2, 4], 2 +pw_approximation = PiecewiseChebyshev(f_x, degree, breakpoints, num_state_qubits) +pw_approximation._build() +qc = QuantumCircuit(pw_approximation.num_qubits) +qc.h(list(range(num_state_qubits))) +qc.append(pw_approximation.to_instruction(), qc.qubits) +qc.draw(output='mpl') +``` + +![../\_images/qiskit-circuit-library-PiecewiseChebyshev-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-PiecewiseChebyshev-1.png) + +**References** + +**\[1]: Haener, T., Roetteler, M., & Svore, K. M. (2018).** + +Optimizing Quantum Circuits for Arithmetic. [arXiv:1805.12445](http://arxiv.org/abs/1805.12445) + +**\[2]: Carrera Vazquez, A., Hiptmair, H., & Woerner, S. (2022).** + +Enhancing the Quantum Linear Systems Algorithm Using Richardson Extrapolation. [ACM Transactions on Quantum Computing 3, 1, Article 2](https://doi.org/10.1145/3490631) + +**Parameters** + +* **f\_x** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – the function to be approximated. Constant functions should be specified as f\_x = constant. +* **degree** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – the degree of the polynomials. Defaults to `1`. +* **breakpoints** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – the breakpoints to define the piecewise-linear function. Defaults to the full interval. +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – number of qubits representing the state. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### breakpoints + +The breakpoints for the piecewise approximation. + +**Returns** + +The breakpoints for the piecewise approximation. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### degree + +The degree of the polynomials. + +**Returns** + +The degree of the polynomials. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### f\_x + +The function to be approximated. + +**Returns** + +The function to be approximated. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 250` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits representing the state $|x\rangle$. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### polynomials + +The polynomials for the piecewise approximation. + +**Returns** + +The polynomials for the piecewise approximation. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the input function is not in the correct format. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseLinearPauliRotations.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseLinearPauliRotations.md new file mode 100644 index 00000000000..27872c7ab47 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewiseLinearPauliRotations.md @@ -0,0 +1,278 @@ +--- +title: PiecewiseLinearPauliRotations +description: API reference for qiskit.circuit.library.PiecewiseLinearPauliRotations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PiecewiseLinearPauliRotations +--- + +# PiecewiseLinearPauliRotations + + + +`qiskit.circuit.library.PiecewiseLinearPauliRotations(num_state_qubits=None, breakpoints=None, slopes=None, offsets=None, basis='Y', name='pw_lin')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/piecewise_linear_pauli_rotations.py "view source code") + +Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") + +Piecewise-linearly-controlled Pauli rotations. + +For a piecewise linear (not necessarily continuous) function $f(x)$, which is defined through breakpoints, slopes and offsets as follows. Suppose the breakpoints $(x_0, ..., x_J)$ are a subset of $[0, 2^n-1]$, where $n$ is the number of state qubits. Further on, denote the corresponding slopes and offsets by $a_j$ and $b_j$ respectively. Then f(x) is defined as: + +$$ +f(x) = \begin{cases} + 0, x < x_0 \\ + a_j (x - x_j) + b_j, x_j \leq x < x_{j+1} + \end{cases} +$$ + +where we implicitly assume $x_{J+1} = 2^n$. + +Construct piecewise-linearly-controlled Pauli rotations. + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits representing the state. +* **breakpoints** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – The breakpoints to define the piecewise-linear function. Defaults to `[0]`. +* **slopes** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | np.ndarray | None*) – The slopes for different segments of the piecewise-linear function. Defaults to `[1]`. +* **offsets** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | np.ndarray | None*) – The offsets for different segments of the piecewise-linear function. Defaults to `[0]`. +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The type of Pauli rotation (`'X'`, `'Y'`, `'Z'`). +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### basis + +The kind of Pauli rotation to be used. + +Set the basis to ‘X’, ‘Y’ or ‘Z’ for controlled-X, -Y, or -Z rotations respectively. + +**Returns** + +The kind of Pauli rotation used in controlled rotation. + + + +### breakpoints + +The breakpoints of the piecewise linear function. + +The function is linear in the intervals `[point_i, point_{i+1}]` where the last point implicitly is `2**(num_state_qubits + 1)`. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### contains\_zero\_breakpoint + +Whether 0 is the first breakpoint. + +**Returns** + +True, if 0 is the first breakpoint, otherwise False. + + + +### data + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 310` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### mapped\_offsets + +The offsets mapped to the internal representation. + +**Returns** + +The mapped offsets. + + + +### mapped\_slopes + +The slopes mapped to the internal representation. + +**Returns** + +The mapped slopes. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +The minimum number of ancilla qubits in the circuit. + +**Returns** + +The minimal number of ancillas required. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits representing the state $|x\rangle$. + +**Returns** + +The number of state qubits. + + + +### offsets + +The breakpoints of the piecewise linear function. + +The function is linear in the intervals `[point_i, point_{i+1}]` where the last point implicitly is `2**(num_state_qubits + 1)`. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### slopes + +The breakpoints of the piecewise linear function. + +The function is linear in the intervals `[point_i, point_{i+1}]` where the last point implicitly is `2**(num_state_qubits + 1)`. + +## Methods + +### evaluate + + + +`evaluate(x)` + +Classically evaluate the piecewise linear rotation. + +**Parameters** + +**x** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value to be evaluated at. + +**Returns** + +Value of piecewise linear function at x. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md new file mode 100644 index 00000000000..8899b5cde63 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PiecewisePolynomialPauliRotations.md @@ -0,0 +1,310 @@ +--- +title: PiecewisePolynomialPauliRotations +description: API reference for qiskit.circuit.library.PiecewisePolynomialPauliRotations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PiecewisePolynomialPauliRotations +--- + +# PiecewisePolynomialPauliRotations + + + +`qiskit.circuit.library.PiecewisePolynomialPauliRotations(num_state_qubits=None, breakpoints=None, coeffs=None, basis='Y', name='pw_poly')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/piecewise_polynomial_pauli_rotations.py "view source code") + +Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") + +Piecewise-polynomially-controlled Pauli rotations. + +This class implements a piecewise polynomial (not necessarily continuous) function, $f(x)$, on qubit amplitudes, which is defined through breakpoints and coefficients as follows. Suppose the breakpoints $(x_0, ..., x_J)$ are a subset of $[0, 2^n-1]$, where $n$ is the number of state qubits. Further on, denote the corresponding coefficients by $[a_{j,1},...,a_{j,d}]$, where $d$ is the highest degree among all polynomials. + +Then $f(x)$ is defined as: + +$$ +f(x) = \begin{cases} + 0, x < x_0 \\ + \sum_{i=0}^{i=d}a_{j,i}/2 x^i, x_j \leq x < x_{j+1} + \end{cases} +$$ + +where if given the same number of breakpoints as polynomials, we implicitly assume $x_{J+1} = 2^n$. + + + Note the $1/2$ factor in the coefficients of $f(x)$, this is consistent with Qiskit’s Pauli rotations. + + +**Examples** + +```python +>>> from qiskit import QuantumCircuit +>>> from qiskit.circuit.library.arithmetic.piecewise_polynomial_pauli_rotations import\ +... PiecewisePolynomialPauliRotations +>>> qubits, breakpoints, coeffs = (2, [0, 2], [[0, -1.2],[-1, 1, 3]]) +>>> poly_r = PiecewisePolynomialPauliRotations(num_state_qubits=qubits, +...breakpoints=breakpoints, coeffs=coeffs) +>>> +>>> qc = QuantumCircuit(poly_r.num_qubits) +>>> qc.h(list(range(qubits))); +>>> qc.append(poly_r.to_instruction(), list(range(qc.num_qubits))); +>>> qc.draw() + ┌───┐┌──────────┐ +q_0: ┤ H ├┤0 ├ + ├───┤│ │ +q_1: ┤ H ├┤1 ├ + └───┘│ │ +q_2: ─────┤2 ├ + │ pw_poly │ +q_3: ─────┤3 ├ + │ │ +q_4: ─────┤4 ├ + │ │ +q_5: ─────┤5 ├ + └──────────┘ +``` + +**References** + +**\[1]: Haener, T., Roetteler, M., & Svore, K. M. (2018).** + +Optimizing Quantum Circuits for Arithmetic. [arXiv:1805.12445](http://arxiv.org/abs/1805.12445) + +**\[2]: Carrera Vazquez, A., Hiptmair, R., & Woerner, S. (2022).** + +Enhancing the Quantum Linear Systems Algorithm using Richardson Extrapolation. [ACM Transactions on Quantum Computing 3, 1, Article 2](https://doi.org/10.1145/3490631) + +**Parameters** + +* **num\_state\_qubits** (*Optional\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The number of qubits representing the state. +* **breakpoints** (*Optional\[List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – The breakpoints to define the piecewise-linear function. Defaults to `[0]`. +* **coeffs** (*Optional\[List\[List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]]*) – The coefficients of the polynomials for different segments of the +* **x** (*piecewise-linear function. coeffs\[j]\[i] is the coefficient of the i-th power of*) – +* **polynomial.** (*for the j-th*) – Defaults to linear: `[[1]]`. +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The type of Pauli rotation (`'X'`, `'Y'`, `'Z'`). +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### basis + +The kind of Pauli rotation to be used. + +Set the basis to ‘X’, ‘Y’ or ‘Z’ for controlled-X, -Y, or -Z rotations respectively. + +**Returns** + +The kind of Pauli rotation used in controlled rotation. + + + +### breakpoints + +The breakpoints of the piecewise polynomial function. + +The function is polynomial in the intervals `[point_i, point_{i+1}]` where the last point implicitly is `2**(num_state_qubits + 1)`. + +**Returns** + +The list of breakpoints. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### coeffs + +The coefficients of the polynomials. + +**Returns** + +The polynomial coefficients per interval as nested lists. + + + +### contains\_zero\_breakpoint + +Whether 0 is the first breakpoint. + +**Returns** + +True, if 0 is the first breakpoint, otherwise False. + + + +### data + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 250` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### mapped\_coeffs + +The coefficients mapped to the internal representation, since we only compare x>=breakpoint. + +**Returns** + +The mapped coefficients. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +The minimum number of ancilla qubits in the circuit. + +**Returns** + +The minimal number of ancillas required. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits representing the state $|x\rangle$. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### evaluate + + + +`evaluate(x)` + +Classically evaluate the piecewise polynomial rotation. + +**Parameters** + +**x** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value to be evaluated at. + +**Returns** + +Value of piecewise polynomial function at x. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.PolynomialPauliRotations.md b/docs/api/qiskit/0.46/qiskit.circuit.library.PolynomialPauliRotations.md new file mode 100644 index 00000000000..758cda3a6d2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.PolynomialPauliRotations.md @@ -0,0 +1,238 @@ +--- +title: PolynomialPauliRotations +description: API reference for qiskit.circuit.library.PolynomialPauliRotations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.PolynomialPauliRotations +--- + +# PolynomialPauliRotations + + + +`qiskit.circuit.library.PolynomialPauliRotations(num_state_qubits=None, coeffs=None, basis='Y', name='poly')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/polynomial_pauli_rotations.py "view source code") + +Bases: [`FunctionalPauliRotations`](qiskit.circuit.library.FunctionalPauliRotations "qiskit.circuit.library.arithmetic.functional_pauli_rotations.FunctionalPauliRotations") + +A circuit implementing polynomial Pauli rotations. + +For a polynomial $p(x)$, a basis state $|i\rangle$ and a target qubit $|0\rangle$ this operator acts as: + +$$ +|i\rangle |0\rangle \mapsto \cos\left(\frac{p(i)}{2}\right) |i\rangle |0\rangle ++ \sin\left(\frac{p(i)}{2}\right) |i\rangle |1\rangle +$$ + +Let n be the number of qubits representing the state, d the degree of p(x) and q\_i the qubits, where q\_0 is the least significant qubit. Then for + +$$ +x = \sum_{i=0}^{n-1} 2^i q_i, +$$ + +we can write + +$$ +p(x) = \sum_{j=0}^{j=d} c_j x^j +$$ + +where $c$ are the input coefficients, `coeffs`. + +Prepare an approximation to a state with amplitudes specified by a polynomial. + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits representing the state. +* **coeffs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – The coefficients of the polynomial. `coeffs[i]` is the coefficient of the i-th power of x. Defaults to linear: \[0, 1]. +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The type of Pauli rotation (‘X’, ‘Y’, ‘Z’). +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### basis + +The kind of Pauli rotation to be used. + +Set the basis to ‘X’, ‘Y’ or ‘Z’ for controlled-X, -Y, or -Z rotations respectively. + +**Returns** + +The kind of Pauli rotation used in controlled rotation. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### coeffs + +The coefficients of the polynomial. + +`coeffs[i]` is the coefficient of the i-th power of the function input $x$, that means that the rotation angles are based on the coefficients value, following the formula + +$$ +c_j x^j , j=0, ..., d +$$ + +where $d$ is the degree of the polynomial $p(x)$ and $c$ are the coefficients `coeffs`. + +**Returns** + +The coefficients of the polynomial. + + + +### data + + + +### degree + +Return the degree of the polynomial, equals to the number of coefficients minus 1. + +**Returns** + +The degree of the polynomial. If the coefficients have not been set, return 0. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 253` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancilla\_qubits + +The minimum number of ancilla qubits in the circuit. + +**Returns** + +The minimal number of ancillas required. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits representing the state $|x\rangle$. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.QAOAAnsatz.md b/docs/api/qiskit/0.46/qiskit.circuit.library.QAOAAnsatz.md new file mode 100644 index 00000000000..d25abeacc79 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.QAOAAnsatz.md @@ -0,0 +1,345 @@ +--- +title: QAOAAnsatz +description: API reference for qiskit.circuit.library.QAOAAnsatz +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.QAOAAnsatz +--- + +# QAOAAnsatz + + + +`qiskit.circuit.library.QAOAAnsatz(cost_operator=None, reps=1, initial_state=None, mixer_operator=None, name='QAOA', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/qaoa_ansatz.py "view source code") + +Bases: [`EvolvedOperatorAnsatz`](qiskit.circuit.library.EvolvedOperatorAnsatz "qiskit.circuit.library.evolved_operator_ansatz.EvolvedOperatorAnsatz") + +A generalized QAOA quantum circuit with a support of custom initial states and mixers. + +**References** + +**\[1]: Farhi et al., A Quantum Approximate Optimization Algorithm.** + +[arXiv:1411.4028](https://arxiv.org/pdf/1411.4028) + +**Parameters** + +* **cost\_operator** (*BaseOperator or* [*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase")*, optional*) – The operator representing the cost of the optimization problem, denoted as $U(C, \gamma)$ in the original paper. Must be set either in the constructor or via property setter. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The integer parameter p, which determines the depth of the circuit, as specified in the original paper, default is 1. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*, optional*) – An optional initial state to use. If None is passed then a set of Hadamard gates is applied as an initial state to all qubits. +* **mixer\_operator** (*BaseOperator or* [*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*, optional*) – An optional custom mixer to use instead of the global X-rotations, denoted as $U(B, \beta)$ in the original paper. Can be an operator or an optionally parameterized quantum circuit. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A name of the circuit, default ‘qaoa’ +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### cost\_operator + +Returns an operator representing the cost of the optimization problem. + +**Returns** + +cost operator. + +**Return type** + +BaseOperator or [OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### evolution + +The evolution converter used to compute the evolution. + +**Returns** + +The evolution converter used to compute the evolution. + +**Return type** + +[EvolutionBase](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.EvolutionBase") or [EvolutionSynthesis](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis") + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Returns an optional initial state as a circuit + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 310` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### mixer\_operator + +Returns an optional mixer operator expressed as an operator or a quantum circuit. + +**Returns** + +mixer operator or circuit. + +**Return type** + +BaseOperator or [OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") or [QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), optional + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### operators + +The operators that are evolved in this circuit. + +**Returns** + +**The operators to be evolved** + +(and circuits) in this ansatz. + +**Return type** + +List\[Union\[BaseOperator, [OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase"), [QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")]] + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If None is returned, problem is fully unbounded. + + + +### parameters + + + +### preferred\_init\_points + +Getter of preferred initial points based on the given initial state. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +Returns the reps parameter, which determines the depth of the circuit. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.QFT.md b/docs/api/qiskit/0.46/qiskit.circuit.library.QFT.md new file mode 100644 index 00000000000..d8e18d99d3c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.QFT.md @@ -0,0 +1,249 @@ +--- +title: QFT +description: API reference for qiskit.circuit.library.QFT +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.QFT +--- + +# QFT + + + +`qiskit.circuit.library.QFT(num_qubits=None, approximation_degree=0, do_swaps=True, inverse=False, insert_barriers=False, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/basis_change/qft.py "view source code") + +Bases: `BlueprintCircuit` + +Quantum Fourier Transform Circuit. + +The Quantum Fourier Transform (QFT) on $n$ qubits is the operation + +$$ +|j\rangle \mapsto \frac{1}{2^{n/2}} \sum_{k=0}^{2^n - 1} e^{2\pi ijk / 2^n} |k\rangle +$$ + +The circuit that implements this transformation can be implemented using Hadamard gates on each qubit, a series of controlled-U1 (or Z, depending on the phase) gates and a layer of Swap gates. The layer of Swap gates can in principle be dropped if the QFT appears at the end of the circuit, since then the re-ordering can be done classically. They can be turned off using the `do_swaps` attribute. + +For 4 qubits, the circuit that implements this transformation is: + +![../\_images/qiskit-circuit-library-QFT-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-QFT-1.png) + +The inverse QFT can be obtained by calling the `inverse` method on this class. The respective circuit diagram is: + +![../\_images/qiskit-circuit-library-QFT-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-QFT-2.png) + +One method to reduce circuit depth is to implement the QFT approximately by ignoring controlled-phase rotations where the angle is beneath a threshold. This is discussed in more detail in [https://arxiv.org/abs/quant-ph/9601018](https://arxiv.org/abs/quant-ph/9601018) or [https://arxiv.org/abs/quant-ph/0403071](https://arxiv.org/abs/quant-ph/0403071). + +Here, this can be adjusted using the `approximation_degree` attribute: the smallest `approximation_degree` rotation angles are dropped from the QFT. For instance, a QFT on 5 qubits with approximation degree 2 yields (the barriers are dropped in this example): + +![../\_images/qiskit-circuit-library-QFT-3.png](/images/api/qiskit/0.46/qiskit-circuit-library-QFT-3.png) + +Construct a new QFT circuit. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits on which the QFT acts. +* **approximation\_degree** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The degree of approximation (0 for no approximation). +* **do\_swaps** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to include the final swaps in the QFT. +* **inverse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, the inverse Fourier transform is constructed. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted as visualization improvement. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### approximation\_degree + +The approximation degree of the QFT. + +**Returns** + +The currently set approximation degree. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### do\_swaps + +Whether the final swaps of the QFT are applied or not. + +**Returns** + +True, if the final swaps are applied, False if not. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### insert\_barriers + +Whether barriers are inserted for better visualization or not. + +**Returns** + +True, if barriers are inserted, False if not. + + + +### instances + +`= 208` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + + + +### num\_qubits + +The number of qubits in the QFT circuit. + +**Returns** + +The number of qubits in the circuit. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### inverse + + + +`inverse()` + +Invert this circuit. + +**Returns** + +The inverted circuit. + +**Return type** + +[*QFT*](#qiskit.circuit.library.QFT "qiskit.circuit.library.basis_change.qft.QFT") + +### is\_inverse + + + +`is_inverse()` + +Whether the inverse Fourier transform is implemented. + +**Returns** + +True, if the inverse Fourier transform is implemented, False otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.QuadraticForm.md b/docs/api/qiskit/0.46/qiskit.circuit.library.QuadraticForm.md new file mode 100644 index 00000000000..385b536442b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.QuadraticForm.md @@ -0,0 +1,272 @@ +--- +title: QuadraticForm +description: API reference for qiskit.circuit.library.QuadraticForm +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.QuadraticForm +--- + +# QuadraticForm + + + +`qiskit.circuit.library.QuadraticForm(num_result_qubits=None, quadratic=None, linear=None, offset=None, little_endian=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/quadratic_form.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Implements a quadratic form on binary variables encoded in qubit registers. + +A quadratic form on binary variables is a quadratic function $Q$ acting on a binary variable of $n$ bits, $x = x_0 ... x_{n-1}$. For an integer matrix $A$, an integer vector $b$ and an integer $c$ the function can be written as + +$$ +Q(x) = x^T A x + x^T b + c +$$ + +If $A$, $b$ or $c$ contain scalar values, this circuit computes only an approximation of the quadratic form. + +Provided with $m$ qubits to encode the value, this circuit computes $Q(x) \mod 2^m$ in \[two’s complement]\([https://stackoverflow.com/questions/1049722/what-is-2s-complement](https://stackoverflow.com/questions/1049722/what-is-2s-complement)) representation. + +$$ +|x\rangle_n |0\rangle_m \mapsto |x\rangle_n |(Q(x) + 2^m) \mod 2^m \rangle_m +$$ + +Since we use two’s complement e.g. the value of $Q(x) = 3$ requires 2 bits to represent the value and 1 bit for the sign: 3 = ‘011’ where the first 0 indicates a positive value. On the other hand, $Q(x) = -3$ would be -3 = ‘101’, where the first 1 indicates a negative value and 01 is the two’s complement of 3. + +If the value of $Q(x)$ is too large to be represented with m qubits, the resulting bitstring is $(Q(x) + 2^m) \mod 2^m)$. + +The implementation of this circuit is discussed in \[1], Fig. 6. + +**References** + +**\[1]: Gilliam et al., Grover Adaptive Search for Constrained Polynomial Binary Optimization.** + +[arXiv:1912.04088](https://arxiv.org/pdf/1912.04088.pdf) + +**Parameters** + +* **num\_result\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits to encode the result. Called $m$ in the class documentation. +* **quadratic** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]] | None*) – A matrix containing the quadratic coefficients, $A$. +* **linear** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] | None*) – An array containing the linear coefficients, $b$. +* **offset** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – A constant offset, $c$. +* **little\_endian** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Encode the result in little endianness. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `linear` and `quadratic` have mismatching sizes. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `num_result_qubits` is unspecified but cannot be determined because some values of the quadratic form are parameterized. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 322` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + +## Methods + +### required\_result\_qubits + + + +`static required_result_qubits(quadratic, linear, offset)` + +Get the number of required result qubits. + +**Parameters** + +* **quadratic** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – A matrix containing the quadratic coefficients. +* **linear** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – An array containing the linear coefficients. +* **offset** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – A constant offset. + +**Returns** + +The number of qubits needed to represent the value of the quadratic form in twos complement. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.QuantumVolume.md b/docs/api/qiskit/0.46/qiskit.circuit.library.QuantumVolume.md new file mode 100644 index 00000000000..620a6ab7643 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.QuantumVolume.md @@ -0,0 +1,234 @@ +--- +title: QuantumVolume +description: API reference for qiskit.circuit.library.QuantumVolume +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.QuantumVolume +--- + +# QuantumVolume + + + +`qiskit.circuit.library.QuantumVolume(num_qubits, depth=None, seed=None, classical_permutation=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/quantum_volume.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +A quantum volume model circuit. + +The model circuits are random instances of circuits used to measure the Quantum Volume metric, as introduced in \[1]. + +The model circuits consist of layers of Haar random elements of SU(4) applied between corresponding pairs of qubits in a random bipartition. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-QuantumVolume-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-QuantumVolume-1.png) + +**Expanded Circuit:** + +![../\_images/qiskit-circuit-library-QuantumVolume-2.png](/images/api/qiskit/0.46/qiskit-circuit-library-QuantumVolume-2.png) + +**References:** + +\[1] A. Cross et al. Validating quantum computers using randomized model circuits, Phys. Rev. A 100, 032328 (2019). \[[arXiv:1811.12926](https://arxiv.org/abs/1811.12926)] + +Create quantum volume model circuit of size num\_qubits x depth. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of active qubits in model circuit. +* **depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – layers of SU(4) operations in model circuit. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Generator*](https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator "(in NumPy v1.26)") *| None*) – Random number generator or generator seed. +* **classical\_permutation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – use classical permutations at every layer, rather than quantum. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 325` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RC3XGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RC3XGate.md new file mode 100644 index 00000000000..d4617ce80b3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RC3XGate.md @@ -0,0 +1,123 @@ +--- +title: RC3XGate +description: API reference for qiskit.circuit.library.RC3XGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RC3XGate +--- + +# RC3XGate + + + +`qiskit.circuit.library.RC3XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The simplified 3-controlled Toffoli gate. + +The simplified Toffoli gate implements the Toffoli gate up to relative phases. Note, that the simplified Toffoli is not equivalent to the Toffoli. But can be used in places where the Toffoli gate is uncomputed again. + +This concrete implementation is from [https://arxiv.org/abs/1508.03273](https://arxiv.org/abs/1508.03273), the complete circuit of Fig. 4. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rcccx()`](qiskit.circuit.QuantumCircuit#rcccx "qiskit.circuit.QuantumCircuit.rcccx") method. + +Create a new RC3X gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RC3XGate.base_class "qiskit.circuit.library.RC3XGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RCCXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RCCXGate.md new file mode 100644 index 00000000000..3c9d4e88933 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RCCXGate.md @@ -0,0 +1,123 @@ +--- +title: RCCXGate +description: API reference for qiskit.circuit.library.RCCXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RCCXGate +--- + +# RCCXGate + + + +`qiskit.circuit.library.RCCXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The simplified Toffoli gate, also referred to as Margolus gate. + +The simplified Toffoli gate implements the Toffoli gate up to relative phases. This implementation requires three CX gates which is the minimal amount possible, as shown in [https://arxiv.org/abs/quant-ph/0312225](https://arxiv.org/abs/quant-ph/0312225). Note, that the simplified Toffoli is not equivalent to the Toffoli. But can be used in places where the Toffoli gate is uncomputed again. + +This concrete implementation is from [https://arxiv.org/abs/1508.03273](https://arxiv.org/abs/1508.03273), the dashed box of Fig. 3. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rccx()`](qiskit.circuit.QuantumCircuit#rccx "qiskit.circuit.QuantumCircuit.rccx") method. + +Create a new simplified CCX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RCCXGate.base_class "qiskit.circuit.library.RCCXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RGQFTMultiplier.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RGQFTMultiplier.md new file mode 100644 index 00000000000..831bf1e42b8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RGQFTMultiplier.md @@ -0,0 +1,256 @@ +--- +title: RGQFTMultiplier +description: API reference for qiskit.circuit.library.RGQFTMultiplier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RGQFTMultiplier +--- + +# RGQFTMultiplier + + + +`qiskit.circuit.library.RGQFTMultiplier(num_state_qubits, num_result_qubits=None, name='RGQFTMultiplier')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/multipliers/rg_qft_multiplier.py "view source code") + +Bases: `Multiplier` + +A QFT multiplication circuit to store product of two input registers out-of-place. + +Multiplication in this circuit is implemented using the procedure of Fig. 3 in \[1], where weighted sum rotations are implemented as given in Fig. 5 in \[1]. QFT is used on the output register and is followed by rotations controlled by input registers. The rotations transform the state into the product of two input registers in QFT base, which is reverted from QFT base using inverse QFT. As an example, a circuit that performs a modular QFT multiplication on two 2-qubit sized input registers with an output register of 2 qubits, is as follows: + +```python + a_0: ────────────────────────────────────────■───────■──────■──────■──────────────── + │ │ │ │ + a_1: ─────────■───────■───────■───────■──────┼───────┼──────┼──────┼──────────────── + │ │ │ │ │ │ │ │ + b_0: ─────────┼───────┼───────■───────■──────┼───────┼──────■──────■──────────────── + │ │ │ │ │ │ │ │ + b_1: ─────────■───────■───────┼───────┼──────■───────■──────┼──────┼──────────────── + ┌──────┐ │P(4π) │ │P(2π) │ │P(2π) │ │P(π) │ ┌───────┐ +out_0: ┤0 ├─■───────┼───────■───────┼──────■───────┼──────■──────┼───────┤0 ├ + │ qft │ │P(2π) │P(π) │P(π) │P(π/2) │ iqft │ +out_1: ┤1 ├─────────■───────────────■──────────────■─────────────■───────┤1 ├ + └──────┘ └───────┘ +``` + +**References:** + +\[1] Ruiz-Perez et al., Quantum arithmetic with the Quantum Fourier Transform, 2017. [arXiv:1411.5949](https://arxiv.org/pdf/1411.5949.pdf) + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits in either input register for state $|a\rangle$ or $|b\rangle$. The two input registers must have the same number of qubits. +* **num\_result\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of result qubits to limit the output to. If number of result qubits is $n$, multiplication modulo $2^n$ is performed to limit the output to the specified number of qubits. Default value is `2 * num_state_qubits` to represent any possible result from the multiplication of the two inputs. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit object. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 456` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### num\_result\_qubits + +The number of result qubits to limit the output to. + +**Returns** + +The number of result qubits. + + + +### num\_state\_qubits + +The number of state qubits, i.e. the number of bits in each input register. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RGate.md new file mode 100644 index 00000000000..d96f8b9f6fe --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RGate.md @@ -0,0 +1,159 @@ +--- +title: RGate +description: API reference for qiskit.circuit.library.RGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RGate +--- + +# RGate + + + +`qiskit.circuit.library.RGate(theta, phi, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/r.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Rotation θ around the cos(φ)x + sin(φ)y axis. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`r()`](qiskit.circuit.QuantumCircuit#r "qiskit.circuit.QuantumCircuit.r") method. + +**Circuit symbol:** + +```python + ┌──────┐ +q_0: ┤ R(ϴ) ├ + └──────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R(\theta, \phi) = e^{-i \rotationangle \left(\cos{\phi} x + \sin{\phi} y\right)} = + \begin{pmatrix} + \cos\left(\rotationangle\right) & -i e^{-i \phi} \sin\left(\rotationangle\right) \\ + -i e^{i \phi} \sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + +Create new r single-qubit gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RGate.base_class "qiskit.circuit.library.RGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Invert this gate. + +r(θ, φ)^dagger = r(-θ, φ) + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RVGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RVGate.md new file mode 100644 index 00000000000..15a56da24df --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RVGate.md @@ -0,0 +1,166 @@ +--- +title: RVGate +description: API reference for qiskit.circuit.library.RVGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RVGate +--- + +# RVGate + + + +`qiskit.circuit.library.RVGate(v_x, v_y, v_z, basis='U')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/rv.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Rotation around arbitrary rotation axis $v$ where $|v|$ is angle of rotation in radians. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rv()`](qiskit.circuit.QuantumCircuit#rv "qiskit.circuit.QuantumCircuit.rv") method. + +**Circuit symbol:** + +```python + ┌─────────────────┐ +q_0: ┤ RV(v_x,v_y,v_z) ├ + └─────────────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{|\vec{v}|} +\newcommand{\sinc}{\text{sinc}} + R(\vec{v}) = e^{-i \vec{v}\cdot\vec{\sigma}} = + \begin{pmatrix} + \cos\left(\rotationangle\right) -i v_z \sinc\left(\rotationangle\right) + & -(i v_x + v_y) \sinc\left(\rotationangle\right) \\ + -(i v_x - v_y) \sinc\left(\rotationangle\right) + & \cos\left(\rotationangle\right) + i v_z \sinc\left(\rotationangle\right) + \end{pmatrix} +$$ + +Create new rv single-qubit gate. + +**Parameters** + +* **v\_x** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – x-component +* **v\_y** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – y-component +* **v\_z** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – z-component +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, optional*) – basis (see [`OneQubitEulerDecomposer`](qiskit.synthesis.OneQubitEulerDecomposer "qiskit.synthesis.one_qubit.one_qubit_decompose.OneQubitEulerDecomposer")) + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RVGate.base_class "qiskit.circuit.library.RVGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Invert this gate. + +### to\_matrix + + + +`to_matrix()` + +Return a numpy.array for the R(v) gate. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RXGate.md new file mode 100644 index 00000000000..65b3ef7a476 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RXGate.md @@ -0,0 +1,181 @@ +--- +title: RXGate +description: API reference for qiskit.circuit.library.RXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RXGate +--- + +# RXGate + + + +`qiskit.circuit.library.RXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rx.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit rotation about the X axis. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rx()`](qiskit.circuit.QuantumCircuit#rx "qiskit.circuit.QuantumCircuit.rx") method. + +**Circuit symbol:** + +```python + ┌───────┐ +q_0: ┤ Rx(ϴ) ├ + └───────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +RX(\theta) = \exp\left(-i \rotationangle X\right) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) \\ + -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + +Create new RX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RXGate.base_class "qiskit.circuit.library.RXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-RX gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted RX gate. + +$RX(\lambda)^{\dagger} = RX(-\lambda)$ + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RXXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RXXGate.md new file mode 100644 index 00000000000..bcf4ffee144 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RXXGate.md @@ -0,0 +1,183 @@ +--- +title: RXXGate +description: API reference for qiskit.circuit.library.RXXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RXXGate +--- + +# RXXGate + + + +`qiskit.circuit.library.RXXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rxx.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A parametric 2-qubit $X \otimes X$ interaction (rotation about XX). + +This gate is symmetric, and is maximally entangling at $\theta = \pi/2$. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rxx()`](qiskit.circuit.QuantumCircuit#rxx "qiskit.circuit.QuantumCircuit.rxx") method. + +**Circuit Symbol:** + +```python + ┌─────────┐ +q_0: ┤1 ├ + │ Rxx(ϴ) │ +q_1: ┤0 ├ + └─────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{XX}(\theta) = \exp\left(-i \rotationangle X{\otimes}X\right) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & 0 & 0 & -i\sin\left(\rotationangle\right) \\ + 0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) & 0 \\ + 0 & -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) & 0 \\ + -i\sin\left(\rotationangle\right) & 0 & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + +**Examples:** + +> $$ +> R_{XX}(\theta = 0) = I +> $$ +> +> $$ +> R_{XX}(\theta = \pi) = i X \otimes X +> $$ +> +> $$ +> R_{XX}\left(\theta = \frac{\pi}{2}\right) = \frac{1}{\sqrt{2}} +> \begin{pmatrix} +> 1 & 0 & 0 & -i \\ +> 0 & 1 & -i & 0 \\ +> 0 & -i & 1 & 0 \\ +> -i & 0 & 0 & 1 +> \end{pmatrix} +> $$ + +Create new RXX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RXXGate.base_class "qiskit.circuit.library.RXXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse RXX gate (i.e. with the negative rotation angle). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RYGate.md new file mode 100644 index 00000000000..3ae272d4b0a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RYGate.md @@ -0,0 +1,181 @@ +--- +title: RYGate +description: API reference for qiskit.circuit.library.RYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RYGate +--- + +# RYGate + + + +`qiskit.circuit.library.RYGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/ry.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit rotation about the Y axis. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`ry()`](qiskit.circuit.QuantumCircuit#ry "qiskit.circuit.QuantumCircuit.ry") method. + +**Circuit symbol:** + +```python + ┌───────┐ +q_0: ┤ Ry(ϴ) ├ + └───────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +RY(\theta) = \exp\left(-i \rotationangle Y\right) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & -\sin\left(\rotationangle\right) \\ + \sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + +Create new RY gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RYGate.base_class "qiskit.circuit.library.RYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-RY gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted RY gate. + +$RY(\lambda)^{\dagger} = RY(-\lambda)$ + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RYYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RYYGate.md new file mode 100644 index 00000000000..6fc935d7584 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RYYGate.md @@ -0,0 +1,183 @@ +--- +title: RYYGate +description: API reference for qiskit.circuit.library.RYYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RYYGate +--- + +# RYYGate + + + +`qiskit.circuit.library.RYYGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/ryy.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A parametric 2-qubit $Y \otimes Y$ interaction (rotation about YY). + +This gate is symmetric, and is maximally entangling at $\theta = \pi/2$. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`ryy()`](qiskit.circuit.QuantumCircuit#ryy "qiskit.circuit.QuantumCircuit.ryy") method. + +**Circuit Symbol:** + +```python + ┌─────────┐ +q_0: ┤1 ├ + │ Ryy(ϴ) │ +q_1: ┤0 ├ + └─────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{YY}(\theta) = \exp\left(-i \rotationangle Y{\otimes}Y\right) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & 0 & 0 & i\sin\left(\rotationangle\right) \\ + 0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) & 0 \\ + 0 & -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) & 0 \\ + i\sin\left(\rotationangle\right) & 0 & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + +**Examples:** + +> $$ +> R_{YY}(\theta = 0) = I +> $$ +> +> $$ +> R_{YY}(\theta = \pi) = i Y \otimes Y +> $$ +> +> $$ +> R_{YY}\left(\theta = \frac{\pi}{2}\right) = \frac{1}{\sqrt{2}} +> \begin{pmatrix} +> 1 & 0 & 0 & i \\ +> 0 & 1 & -i & 0 \\ +> 0 & -i & 1 & 0 \\ +> i & 0 & 0 & 1 +> \end{pmatrix} +> $$ + +Create new RYY gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RYYGate.base_class "qiskit.circuit.library.RYYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse RYY gate (i.e. with the negative rotation angle). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RZGate.md new file mode 100644 index 00000000000..715fbfb6b2f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RZGate.md @@ -0,0 +1,191 @@ +--- +title: RZGate +description: API reference for qiskit.circuit.library.RZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RZGate +--- + +# RZGate + + + +`qiskit.circuit.library.RZGate(phi, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rz.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit rotation about the Z axis. + +This is a diagonal gate. It can be implemented virtually in hardware via framechanges (i.e. at zero error and duration). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rz()`](qiskit.circuit.QuantumCircuit#rz "qiskit.circuit.QuantumCircuit.rz") method. + +**Circuit symbol:** + +```python + ┌───────┐ +q_0: ┤ Rz(λ) ├ + └───────┘ +``` + +**Matrix Representation:** + +$$ +RZ(\lambda) = \exp\left(-i\frac{\lambda}{2}Z\right) = + \begin{pmatrix} + e^{-i\frac{\lambda}{2}} & 0 \\ + 0 & e^{i\frac{\lambda}{2}} + \end{pmatrix} +$$ + + + `U1Gate` This gate is equivalent to U1 up to a phase factor. + + > $$ + > U1(\lambda) = e^{i{\lambda}/2}RZ(\lambda) + > $$ + + Reference for virtual Z gate implementation: [1612.00858](https://arxiv.org/abs/1612.00858) + + +Create new RZ gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RZGate.base_class "qiskit.circuit.library.RZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-RZ gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted RZ gate + +$RZ(\lambda)^{\dagger} = RZ(-\lambda)$ + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RZXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RZXGate.md new file mode 100644 index 00000000000..06caff0f53f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RZXGate.md @@ -0,0 +1,223 @@ +--- +title: RZXGate +description: API reference for qiskit.circuit.library.RZXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RZXGate +--- + +# RZXGate + + + +`qiskit.circuit.library.RZXGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rzx.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A parametric 2-qubit $Z \otimes X$ interaction (rotation about ZX). + +This gate is maximally entangling at $\theta = \pi/2$. + +The cross-resonance gate (CR) for superconducting qubits implements a ZX interaction (however other terms are also present in an experiment). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rzx()`](qiskit.circuit.QuantumCircuit#rzx "qiskit.circuit.QuantumCircuit.rzx") method. + +**Circuit Symbol:** + +```python + ┌─────────┐ +q_0: ┤0 ├ + │ Rzx(θ) │ +q_1: ┤1 ├ + └─────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{ZX}(\theta)\ q_0, q_1 = \exp\left(-i \frac{\theta}{2} X{\otimes}Z\right) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & 0 & -i\sin\left(\rotationangle\right) & 0 \\ + 0 & \cos\left(\rotationangle\right) & 0 & i\sin\left(\rotationangle\right) \\ + -i\sin\left(\rotationangle\right) & 0 & \cos\left(\rotationangle\right) & 0 \\ + 0 & i\sin\left(\rotationangle\right) & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In the above example we apply the gate on (q\_0, q\_1) which results in the $X \otimes Z$ tensor order. Instead, if we apply it on (q\_1, q\_0), the matrix will be $Z \otimes X$: + + ```python + ┌─────────┐ + q_0: ┤1 ├ + │ Rzx(θ) │ + q_1: ┤0 ├ + └─────────┘ + ``` + + $$ + \newcommand{\rotationangle}{\frac{\theta}{2}} + + R_{ZX}(\theta)\ q_1, q_0 = exp(-i \frac{\theta}{2} Z{\otimes}X) = + \begin{pmatrix} + \cos(\rotationangle) & -i\sin(\rotationangle) & 0 & 0 \\ + -i\sin(\rotationangle) & \cos(\rotationangle) & 0 & 0 \\ + 0 & 0 & \cos(\rotationangle) & i\sin(\rotationangle) \\ + 0 & 0 & i\sin(\rotationangle) & \cos(\rotationangle) + \end{pmatrix} + $$ + + This is a direct sum of RX rotations, so this gate is equivalent to a uniformly controlled (multiplexed) RX gate: + + $$ + R_{ZX}(\theta)\ q_1, q_0 = + \begin{pmatrix} + RX(\theta) & 0 \\ + 0 & RX(-\theta) + \end{pmatrix} + $$ + + +**Examples:** + +> $$ +> R_{ZX}(\theta = 0) = I +> $$ +> +> $$ +> R_{ZX}(\theta = 2\pi) = -I +> $$ +> +> $$ +> R_{ZX}(\theta = \pi) = -i Z \otimes X +> $$ +> +> $$ +> RZX(\theta = \frac{\pi}{2}) = \frac{1}{\sqrt{2}} +> \begin{pmatrix} +> 1 & 0 & -i & 0 \\ +> 0 & 1 & 0 & i \\ +> -i & 0 & 1 & 0 \\ +> 0 & i & 0 & 1 +> \end{pmatrix} +> $$ + +Create new RZX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RZXGate.base_class "qiskit.circuit.library.RZXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse RZX gate (i.e. with the negative rotation angle). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RZZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RZZGate.md new file mode 100644 index 00000000000..793ed5c02b1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RZZGate.md @@ -0,0 +1,195 @@ +--- +title: RZZGate +description: API reference for qiskit.circuit.library.RZZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RZZGate +--- + +# RZZGate + + + +`qiskit.circuit.library.RZZGate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/rzz.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +A parametric 2-qubit $Z \otimes Z$ interaction (rotation about ZZ). + +This gate is symmetric, and is maximally entangling at $\theta = \pi/2$. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`rzz()`](qiskit.circuit.QuantumCircuit#rzz "qiskit.circuit.QuantumCircuit.rzz") method. + +**Circuit Symbol:** + +```python +q_0: ───■──── + │zz(θ) +q_1: ───■──── +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{ZZ}(\theta) = \exp\left(-i \rotationangle Z{\otimes}Z\right) = + \begin{pmatrix} + e^{-i \rotationangle} & 0 & 0 & 0 \\ + 0 & e^{i \rotationangle} & 0 & 0 \\ + 0 & 0 & e^{i \rotationangle} & 0 \\ + 0 & 0 & 0 & e^{-i \rotationangle} + \end{pmatrix} +$$ + +This is a direct sum of RZ rotations, so this gate is equivalent to a uniformly controlled (multiplexed) RZ gate: + +$$ +R_{ZZ}(\theta) = + \begin{pmatrix} + RZ(\theta) & 0 \\ + 0 & RZ(-\theta) + \end{pmatrix} +$$ + +**Examples:** + +> $$ +> R_{ZZ}(\theta = 0) = I +> $$ +> +> $$ +> R_{ZZ}(\theta = 2\pi) = -I +> $$ +> +> $$ +> R_{ZZ}(\theta = \pi) = - Z \otimes Z +> $$ +> +> $$ +> R_{ZZ}\left(\theta = \frac{\pi}{2}\right) = \frac{1}{\sqrt{2}} +> \begin{pmatrix} +> 1-i & 0 & 0 & 0 \\ +> 0 & 1+i & 0 & 0 \\ +> 0 & 0 & 1+i & 0 \\ +> 0 & 0 & 0 & 1-i +> \end{pmatrix} +> $$ + +Create new RZZ gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.RZZGate.base_class "qiskit.circuit.library.RZZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse RZZ gate (i.e. with the negative rotation angle). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.RealAmplitudes.md b/docs/api/qiskit/0.46/qiskit.circuit.library.RealAmplitudes.md new file mode 100644 index 00000000000..d30a05b728c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.RealAmplitudes.md @@ -0,0 +1,389 @@ +--- +title: RealAmplitudes +description: API reference for qiskit.circuit.library.RealAmplitudes +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.RealAmplitudes +--- + +# RealAmplitudes + + + +`qiskit.circuit.library.RealAmplitudes(num_qubits=None, entanglement='reverse_linear', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='RealAmplitudes', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/real_amplitudes.py "view source code") + +Bases: [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.n_local.two_local.TwoLocal") + +The real-amplitudes 2-local circuit. + +The `RealAmplitudes` circuit is a heuristic trial wave function used as Ansatz in chemistry applications or classification circuits in machine learning. The circuit consists of alternating layers of $Y$ rotations and $CX$ entanglements. The entanglement pattern can be user-defined or selected from a predefined set. It is called `RealAmplitudes` since the prepared quantum states will only have real amplitudes, the complex part is always 0. + +For example a `RealAmplitudes` circuit with 2 repetitions on 3 qubits with `'reverse_linear'` entanglement is + +```python +┌──────────┐ ░ ░ ┌──────────┐ ░ ░ ┌──────────┐ +┤ Ry(θ[0]) ├─░────────■───░─┤ Ry(θ[3]) ├─░────────■───░─┤ Ry(θ[6]) ├ +├──────────┤ ░ ┌─┴─┐ ░ ├──────────┤ ░ ┌─┴─┐ ░ ├──────────┤ +┤ Ry(θ[1]) ├─░───■──┤ X ├─░─┤ Ry(θ[4]) ├─░───■──┤ X ├─░─┤ Ry(θ[7]) ├ +├──────────┤ ░ ┌─┴─┐└───┘ ░ ├──────────┤ ░ ┌─┴─┐└───┘ ░ ├──────────┤ +┤ Ry(θ[2]) ├─░─┤ X ├──────░─┤ Ry(θ[5]) ├─░─┤ X ├──────░─┤ Ry(θ[8]) ├ +└──────────┘ ░ └───┘ ░ └──────────┘ ░ └───┘ ░ └──────────┘ +``` + +The entanglement can be set using the `entanglement` keyword as string or a list of index-pairs. See the documentation of [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.TwoLocal") and `NLocal` for more detail. Additional options that can be set include the number of repetitions, skipping rotation gates on qubits that are not entangled, leaving out the final rotation layer and inserting barriers in between the rotation and entanglement layers. + +If some qubits are not entangled with other qubits it makes sense to not apply rotation gates on these qubits, since a sequence of $Y$ rotations can be reduced to a single $Y$ rotation with summed rotation angles. + +**Examples** + +```python +>>> ansatz = RealAmplitudes(3, reps=2) # create the circuit on 3 qubits +>>> print(ansatz) + ┌──────────┐ ┌──────────┐ ┌──────────┐ +q_0: ┤ Ry(θ[0]) ├──────────■──────┤ Ry(θ[3]) ├──────────■──────┤ Ry(θ[6]) ├ + ├──────────┤ ┌─┴─┐ ├──────────┤ ┌─┴─┐ ├──────────┤ +q_1: ┤ Ry(θ[1]) ├──■─────┤ X ├────┤ Ry(θ[4]) ├──■─────┤ X ├────┤ Ry(θ[7]) ├ + ├──────────┤┌─┴─┐┌──┴───┴───┐└──────────┘┌─┴─┐┌──┴───┴───┐└──────────┘ +q_2: ┤ Ry(θ[2]) ├┤ X ├┤ Ry(θ[5]) ├────────────┤ X ├┤ Ry(θ[8]) ├──────────── + └──────────┘└───┘└──────────┘ └───┘└──────────┘ +``` + +```python +>>> ansatz = RealAmplitudes(3, entanglement='full', reps=2) # it is the same unitary as above +>>> print(ansatz) + ┌──────────┐ ┌──────────┐ ┌──────────┐ +q_0: ┤ RY(θ[0]) ├──■────■──┤ RY(θ[3]) ├──────────────■────■──┤ RY(θ[6]) ├──────────── + ├──────────┤┌─┴─┐ │ └──────────┘┌──────────┐┌─┴─┐ │ └──────────┘┌──────────┐ +q_1: ┤ RY(θ[1]) ├┤ X ├──┼───────■──────┤ RY(θ[4]) ├┤ X ├──┼───────■──────┤ RY(θ[7]) ├ + ├──────────┤└───┘┌─┴─┐ ┌─┴─┐ ├──────────┤└───┘┌─┴─┐ ┌─┴─┐ ├──────────┤ +q_2: ┤ RY(θ[2]) ├─────┤ X ├───┤ X ├────┤ RY(θ[5]) ├─────┤ X ├───┤ X ├────┤ RY(θ[8]) ├ + └──────────┘ └───┘ └───┘ └──────────┘ └───┘ └───┘ └──────────┘ +``` + +```python +>>> ansatz = RealAmplitudes(3, entanglement='linear', reps=2, insert_barriers=True) +>>> qc = QuantumCircuit(3) # create a circuit and append the RY variational form +>>> qc.compose(ansatz, inplace=True) +>>> qc.draw() + ┌──────────┐ ░ ░ ┌──────────┐ ░ ░ ┌──────────┐ +q_0: ┤ RY(θ[0]) ├─░───■────────░─┤ RY(θ[3]) ├─░───■────────░─┤ RY(θ[6]) ├ + ├──────────┤ ░ ┌─┴─┐ ░ ├──────────┤ ░ ┌─┴─┐ ░ ├──────────┤ +q_1: ┤ RY(θ[1]) ├─░─┤ X ├──■───░─┤ RY(θ[4]) ├─░─┤ X ├──■───░─┤ RY(θ[7]) ├ + ├──────────┤ ░ └───┘┌─┴─┐ ░ ├──────────┤ ░ └───┘┌─┴─┐ ░ ├──────────┤ +q_2: ┤ RY(θ[2]) ├─░──────┤ X ├─░─┤ RY(θ[5]) ├─░──────┤ X ├─░─┤ RY(θ[8]) ├ + └──────────┘ ░ └───┘ ░ └──────────┘ ░ └───┘ ░ └──────────┘ +``` + +```python +>>> ansatz = RealAmplitudes(4, reps=1, entanglement='circular', insert_barriers=True) +>>> print(ansatz) + ┌──────────┐ ░ ┌───┐ ░ ┌──────────┐ +q_0: ┤ RY(θ[0]) ├─░─┤ X ├──■─────────────░─┤ RY(θ[4]) ├ + ├──────────┤ ░ └─┬─┘┌─┴─┐ ░ ├──────────┤ +q_1: ┤ RY(θ[1]) ├─░───┼──┤ X ├──■────────░─┤ RY(θ[5]) ├ + ├──────────┤ ░ │ └───┘┌─┴─┐ ░ ├──────────┤ +q_2: ┤ RY(θ[2]) ├─░───┼───────┤ X ├──■───░─┤ RY(θ[6]) ├ + ├──────────┤ ░ │ └───┘┌─┴─┐ ░ ├──────────┤ +q_3: ┤ RY(θ[3]) ├─░───■────────────┤ X ├─░─┤ RY(θ[7]) ├ + └──────────┘ ░ └───┘ ░ └──────────┘ +``` + +```python +>>> ansatz = RealAmplitudes(4, reps=2, entanglement=[[0,3], [0,2]], +... skip_unentangled_qubits=True) +>>> print(ansatz) + ┌──────────┐ ┌──────────┐ ┌──────────┐ +q_0: ┤ RY(θ[0]) ├──■───────■──────┤ RY(θ[3]) ├──■───────■──────┤ RY(θ[6]) ├ + └──────────┘ │ │ └──────────┘ │ │ └──────────┘ +q_1: ──────────────┼───────┼────────────────────┼───────┼────────────────── + ┌──────────┐ │ ┌─┴─┐ ┌──────────┐ │ ┌─┴─┐ ┌──────────┐ +q_2: ┤ RY(θ[1]) ├──┼─────┤ X ├────┤ RY(θ[4]) ├──┼─────┤ X ├────┤ RY(θ[7]) ├ + ├──────────┤┌─┴─┐┌──┴───┴───┐└──────────┘┌─┴─┐┌──┴───┴───┐└──────────┘ +q_3: ┤ RY(θ[2]) ├┤ X ├┤ RY(θ[5]) ├────────────┤ X ├┤ RY(θ[8]) ├──────────── + └──────────┘└───┘└──────────┘ └───┘└──────────┘ +``` + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits of the RealAmplitudes circuit. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Specifies how often the structure of a rotation layer followed by an entanglement layer is repeated. +* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Specifies the entanglement structure. Can be a string (‘full’, ‘linear’ ‘reverse\_linear, ‘circular’ or ‘sca’), a list of integer-pairs specifying the indices of qubits entangled with one another, or a callable returning such a list provided with the index of the entanglement layer. Default to ‘reverse\_linear’ entanglement. Note that ‘reverse\_linear’ entanglement provides the same unitary as ‘full’ with fewer entangling gates. See the Examples section of [`TwoLocal`](qiskit.circuit.library.TwoLocal "qiskit.circuit.library.TwoLocal") for more detail. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A QuantumCircuit object to prepend to the circuit. +* **skip\_unentangled\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, the single qubit gates are only applied to qubits that are entangled with another qubit. If False, the single qubit gates are applied to each qubit in the Ansatz. Defaults to False. +* **skip\_final\_rotation\_layer** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If False, a rotation layer is added at the end of the ansatz. If True, no rotation layer is added. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The parameterized gates require a parameter to be defined, for which we use [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector"). +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted in between each layer. If False, no barriers are inserted. +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +Return the parameter bounds. + +**Returns** + +The parameter bounds. + + + +### parameters + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.Reset.md b/docs/api/qiskit/0.46/qiskit.circuit.library.Reset.md new file mode 100644 index 00000000000..e4a701a60dd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.Reset.md @@ -0,0 +1,316 @@ +--- +title: Reset +description: API reference for qiskit.circuit.library.Reset +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.Reset +--- + +# Reset + + + +`qiskit.circuit.library.Reset(label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/reset.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Qubit reset. + +Create new reset instruction. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.Reset.base_class "qiskit.circuit.library.Reset.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Invert this instruction. + +If the instruction is composite (i.e. has a definition), then its definition will be recursively inverted. + +Special instructions inheriting from Instruction can implement their own inverse (e.g. T and Tdg, Barrier, etc.) + +**Returns** + +a fresh instruction for the inverse + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the instruction is not composite and an inverse has not been implemented for it. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.SGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.SGate.md new file mode 100644 index 00000000000..e728a415e31 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.SGate.md @@ -0,0 +1,160 @@ +--- +title: SGate +description: API reference for qiskit.circuit.library.SGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.SGate +--- + +# SGate + + + +`qiskit.circuit.library.SGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/s.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Single qubit S gate (Z\*\*0.5). + +It induces a $\pi/2$ phase, and is sometimes called the P gate (phase). + +This is a Clifford gate and a square-root of Pauli-Z. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`s()`](qiskit.circuit.QuantumCircuit#s "qiskit.circuit.QuantumCircuit.s") method. + +**Matrix Representation:** + +$$ +S = \begin{pmatrix} + 1 & 0 \\ + 0 & i + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ S ├ + └───┘ +``` + +Equivalent to a $\pi/2$ radian rotation about the Z axis. + +Create new S gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.SGate.base_class "qiskit.circuit.library.SGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse of S (SdgGate). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.SXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.SXGate.md new file mode 100644 index 00000000000..9dbd8e82f2e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.SXGate.md @@ -0,0 +1,182 @@ +--- +title: SXGate +description: API reference for qiskit.circuit.library.SXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.SXGate +--- + +# SXGate + + + +`qiskit.circuit.library.SXGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/sx.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The single-qubit Sqrt(X) gate ($\sqrt{X}$). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`sx()`](qiskit.circuit.QuantumCircuit#sx "qiskit.circuit.QuantumCircuit.sx") method. + +**Matrix Representation:** + +$$ +\sqrt{X} = \frac{1}{2} \begin{pmatrix} + 1 + i & 1 - i \\ + 1 - i & 1 + i + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌────┐ +q_0: ┤ √X ├ + └────┘ +``` + + + A global phase difference exists between the definitions of $RX(\pi/2)$ and $\sqrt{X}$. + + $$ + RX(\pi/2) = \frac{1}{\sqrt{2}} \begin{pmatrix} + 1 & -i \\ + -i & 1 + \end{pmatrix} + = e^{-i \pi/4} \sqrt{X} + $$ + + +Create new SX gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.SXGate.base_class "qiskit.circuit.library.SXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-SX gate. + +One control returns a CSX gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[SingletonControlledGate](circuit_singleton#qiskit.circuit.singleton.SingletonControlledGate "qiskit.circuit.singleton.SingletonControlledGate") + +### inverse + + + +`inverse()` + +Return inverse SX gate (i.e. SXdg). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.SXdgGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.SXdgGate.md new file mode 100644 index 00000000000..849043ed5d1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.SXdgGate.md @@ -0,0 +1,148 @@ +--- +title: SXdgGate +description: API reference for qiskit.circuit.library.SXdgGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.SXdgGate +--- + +# SXdgGate + + + +`qiskit.circuit.library.SXdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/sx.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The inverse single-qubit Sqrt(X) gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`sxdg()`](qiskit.circuit.QuantumCircuit#sxdg "qiskit.circuit.QuantumCircuit.sxdg") method. + +$$ +\sqrt{X}^{\dagger} = \frac{1}{2} \begin{pmatrix} + 1 - i & 1 + i \\ + 1 + i & 1 - i + \end{pmatrix} +$$ + + + A global phase difference exists between the definitions of $RX(-\pi/2)$ and $\sqrt{X}^{\dagger}$. + + $$ + RX(-\pi/2) = \frac{1}{\sqrt{2}} \begin{pmatrix} + 1 & i \\ + i & 1 + \end{pmatrix} + = e^{-i \pi/4} \sqrt{X}^{\dagger} + $$ + + +Create new SXdg gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.SXdgGate.base_class "qiskit.circuit.library.SXdgGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse SXdg gate (i.e. SX). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.SdgGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.SdgGate.md new file mode 100644 index 00000000000..1607bf2903c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.SdgGate.md @@ -0,0 +1,160 @@ +--- +title: SdgGate +description: API reference for qiskit.circuit.library.SdgGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.SdgGate +--- + +# SdgGate + + + +`qiskit.circuit.library.SdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/s.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Single qubit S-adjoint gate (\~Z\*\*0.5). + +It induces a $-\pi/2$ phase. + +This is a Clifford gate and a square-root of Pauli-Z. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`sdg()`](qiskit.circuit.QuantumCircuit#sdg "qiskit.circuit.QuantumCircuit.sdg") method. + +**Matrix Representation:** + +$$ +Sdg = \begin{pmatrix} + 1 & 0 \\ + 0 & -i + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌─────┐ +q_0: ┤ Sdg ├ + └─────┘ +``` + +Equivalent to a $-\pi/2$ radian rotation about the Z axis. + +Create new Sdg gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.SdgGate.base_class "qiskit.circuit.library.SdgGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse of Sdg (SGate). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.StatePreparation.md b/docs/api/qiskit/0.46/qiskit.circuit.library.StatePreparation.md new file mode 100644 index 00000000000..f5454e0cd7e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.StatePreparation.md @@ -0,0 +1,211 @@ +--- +title: StatePreparation +description: API reference for qiskit.circuit.library.StatePreparation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.StatePreparation +--- + +# StatePreparation + + + +`qiskit.circuit.library.StatePreparation(params, num_qubits=None, inverse=False, label=None, normalize=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/data_preparation/state_preparation.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Complex amplitude state preparation. + +Class that implements the (complex amplitude) state preparation of some flexible collection of qubit registers. + +**Parameters** + +* **params** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector")) – + + * Statevector: Statevector to initialize to. + * list: vector of complex amplitudes to initialize to. + * string: labels of basis states of the Pauli eigenstates Z, X, Y. See [`Statevector.from_label()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label"). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to $|1\rangle$ and the qubit one to $|0\rangle$. + * int: an integer that is used as a bitmap indicating which qubits to initialize to $|1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $|1\rangle$ and qubit 1 to $|0\rangle$. + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – This parameter is only used if params is an int. Indicates the total number of qubits in the initialize call. Example: initialize covers 5 qubits and params is 3. This allows qubits 0 and 1 to be initialized to $|1\rangle$ and the remaining 3 qubits to be initialized to $|0\rangle$. + +* **inverse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, the inverse state is constructed. + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – An optional label for the gate + +* **normalize** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to normalize an input array to a unit vector. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – `num_qubits` parameter used when `params` is not an integer + +When a Statevector argument is passed the state is prepared using a recursive initialization algorithm, including optimizations, from \[1], as well as some additional optimizations including removing zero rotations and double cnots. + +**References:** \[1] Shende, Bullock, Markov. Synthesis of Quantum Logic Circuits (2004) \[[https://arxiv.org/abs/quant-ph/0406176v5](https://arxiv.org/abs/quant-ph/0406176v5)] + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.StatePreparation.base_class "qiskit.circuit.library.StatePreparation.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** – List of quantum bit arguments. +* **cargs** – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### inverse + + + +`inverse()` + +Return inverted StatePreparation + +### validate\_parameter + + + +`validate_parameter(parameter)` + +StatePreparation instruction parameter can be str, int, float, and complex. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.SwapGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.SwapGate.md new file mode 100644 index 00000000000..79b2c2e8936 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.SwapGate.md @@ -0,0 +1,181 @@ +--- +title: SwapGate +description: API reference for qiskit.circuit.library.SwapGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.SwapGate +--- + +# SwapGate + + + +`qiskit.circuit.library.SwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/swap.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The SWAP gate. + +This is a symmetric and Clifford gate. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`swap()`](qiskit.circuit.QuantumCircuit#swap "qiskit.circuit.QuantumCircuit.swap") method. + +**Circuit symbol:** + +```python +q_0: ─X─ + │ +q_1: ─X─ +``` + +**Matrix Representation:** + +$$ +SWAP = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & 1 + \end{pmatrix} +$$ + +The gate is equivalent to a state swap and is a classical logic gate. + +$$ +|a, b\rangle \rightarrow |b, a\rangle +$$ + +Create new SWAP gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.SwapGate.base_class "qiskit.circuit.library.SwapGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-SWAP gate. + +One control returns a CSWAP (Fredkin) gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverse Swap gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.TGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.TGate.md new file mode 100644 index 00000000000..09bf8711113 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.TGate.md @@ -0,0 +1,160 @@ +--- +title: TGate +description: API reference for qiskit.circuit.library.TGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.TGate +--- + +# TGate + + + +`qiskit.circuit.library.TGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/t.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Single qubit T gate (Z\*\*0.25). + +It induces a $\pi/4$ phase, and is sometimes called the pi/8 gate (because of how the RZ(pi/4) matrix looks like). + +This is a non-Clifford gate and a fourth-root of Pauli-Z. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`t()`](qiskit.circuit.QuantumCircuit#t "qiskit.circuit.QuantumCircuit.t") method. + +**Matrix Representation:** + +$$ +T = \begin{pmatrix} + 1 & 0 \\ + 0 & e^{i\pi/4} + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ T ├ + └───┘ +``` + +Equivalent to a $\pi/4$ radian rotation about the Z axis. + +Create new T gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.TGate.base_class "qiskit.circuit.library.TGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse T gate (i.e. Tdg). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.TdgGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.TdgGate.md new file mode 100644 index 00000000000..952b408560e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.TdgGate.md @@ -0,0 +1,160 @@ +--- +title: TdgGate +description: API reference for qiskit.circuit.library.TdgGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.TdgGate +--- + +# TdgGate + + + +`qiskit.circuit.library.TdgGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/t.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +Single qubit T-adjoint gate (\~Z\*\*0.25). + +It induces a $-\pi/4$ phase. + +This is a non-Clifford gate and a fourth-root of Pauli-Z. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`tdg()`](qiskit.circuit.QuantumCircuit#tdg "qiskit.circuit.QuantumCircuit.tdg") method. + +**Matrix Representation:** + +$$ +Tdg = \begin{pmatrix} + 1 & 0 \\ + 0 & e^{-i\pi/4} + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌─────┐ +q_0: ┤ Tdg ├ + └─────┘ +``` + +Equivalent to a $-\pi/4$ radian rotation about the Z axis. + +Create new Tdg gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.TdgGate.base_class "qiskit.circuit.library.TdgGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse Tdg gate (i.e. T). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.TwoLocal.md b/docs/api/qiskit/0.46/qiskit.circuit.library.TwoLocal.md new file mode 100644 index 00000000000..9b04820924e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.TwoLocal.md @@ -0,0 +1,415 @@ +--- +title: TwoLocal +description: API reference for qiskit.circuit.library.TwoLocal +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.TwoLocal +--- + +# TwoLocal + + + +`qiskit.circuit.library.TwoLocal(num_qubits=None, rotation_blocks=None, entanglement_blocks=None, entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, initial_state=None, name='TwoLocal', flatten=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/n_local/two_local.py "view source code") + +Bases: [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.n_local.n_local.NLocal") + +The two-local circuit. + +The two-local circuit is a parameterized circuit consisting of alternating rotation layers and entanglement layers. The rotation layers are single qubit gates applied on all qubits. The entanglement layer uses two-qubit gates to entangle the qubits according to a strategy set using `entanglement`. Both the rotation and entanglement gates can be specified as string (e.g. `'ry'` or `'cx'`), as gate-type (e.g. `RYGate` or `CXGate`) or as QuantumCircuit (e.g. a 1-qubit circuit or 2-qubit circuit). + +A set of default entanglement strategies is provided: + +* `'full'` entanglement is each qubit is entangled with all the others. +* `'linear'` entanglement is qubit $i$ entangled with qubit $i + 1$, for all $i \in \{0, 1, ... , n - 2\}$, where $n$ is the total number of qubits. +* `'reverse_linear'` entanglement is qubit $i$ entangled with qubit $i + 1$, for all $i \in \{n-2, n-3, ... , 1, 0\}$, where $n$ is the total number of qubits. Note that if `entanglement_blocks = 'cx'` then this option provides the same unitary as `'full'` with fewer entangling gates. +* `'pairwise'` entanglement is one layer where qubit $i$ is entangled with qubit $i + 1$, for all even values of $i$, and then a second layer where qubit $i$ is entangled with qubit $i + 1$, for all odd values of $i$. +* `'circular'` entanglement is linear entanglement but with an additional entanglement of the first and last qubit before the linear part. +* `'sca'` (shifted-circular-alternating) entanglement is a generalized and modified version of the proposed circuit 14 in [Sim et al.](https://arxiv.org/abs/1905.10876). It consists of circular entanglement where the ‘long’ entanglement connecting the first with the last qubit is shifted by one each block. Furthermore the role of control and target qubits are swapped every block (therefore alternating). + +The entanglement can further be specified using an entangler map, which is a list of index pairs, such as + +```python +>>> entangler_map = [(0, 1), (1, 2), (2, 0)] +``` + +If different entanglements per block should be used, provide a list of entangler maps. See the examples below on how this can be used. + +```python +>>> entanglement = [entangler_map_layer_1, entangler_map_layer_2, ... ] +``` + +Barriers can be inserted in between the different layers for better visualization using the `insert_barriers` attribute. + +For each parameterized gate a new parameter is generated using a `ParameterVector`. The name of these parameters can be chosen using the `parameter_prefix`. + +**Examples** + +```python +>>> two = TwoLocal(3, 'ry', 'cx', 'linear', reps=2, insert_barriers=True) +>>> print(two) # decompose the layers into standard gates + ┌──────────┐ ░ ░ ┌──────────┐ ░ ░ ┌──────────┐ +q_0: ┤ Ry(θ[0]) ├─░───■────────░─┤ Ry(θ[3]) ├─░───■────────░─┤ Ry(θ[6]) ├ + ├──────────┤ ░ ┌─┴─┐ ░ ├──────────┤ ░ ┌─┴─┐ ░ ├──────────┤ +q_1: ┤ Ry(θ[1]) ├─░─┤ X ├──■───░─┤ Ry(θ[4]) ├─░─┤ X ├──■───░─┤ Ry(θ[7]) ├ + ├──────────┤ ░ └───┘┌─┴─┐ ░ ├──────────┤ ░ └───┘┌─┴─┐ ░ ├──────────┤ +q_2: ┤ Ry(θ[2]) ├─░──────┤ X ├─░─┤ Ry(θ[5]) ├─░──────┤ X ├─░─┤ Ry(θ[8]) ├ + └──────────┘ ░ └───┘ ░ └──────────┘ ░ └───┘ ░ └──────────┘ +``` + +```python +>>> two = TwoLocal(3, ['ry','rz'], 'cz', 'full', reps=1, insert_barriers=True) +>>> qc = QuantumCircuit(3) +>>> qc += two +>>> print(qc.decompose().draw()) + ┌──────────┐┌──────────┐ ░ ░ ┌──────────┐ ┌──────────┐ +q_0: ┤ Ry(θ[0]) ├┤ Rz(θ[3]) ├─░──■──■─────░─┤ Ry(θ[6]) ├─┤ Rz(θ[9]) ├ + ├──────────┤├──────────┤ ░ │ │ ░ ├──────────┤┌┴──────────┤ +q_1: ┤ Ry(θ[1]) ├┤ Rz(θ[4]) ├─░──■──┼──■──░─┤ Ry(θ[7]) ├┤ Rz(θ[10]) ├ + ├──────────┤├──────────┤ ░ │ │ ░ ├──────────┤├───────────┤ +q_2: ┤ Ry(θ[2]) ├┤ Rz(θ[5]) ├─░─────■──■──░─┤ Ry(θ[8]) ├┤ Rz(θ[11]) ├ + └──────────┘└──────────┘ ░ ░ └──────────┘└───────────┘ +``` + +```python +>>> entangler_map = [[0, 1], [1, 2], [2, 0]] # circular entanglement for 3 qubits +>>> two = TwoLocal(3, 'x', 'crx', entangler_map, reps=1) +>>> print(two) # note: no barriers inserted this time! + ┌───┐ ┌──────────┐┌───┐ +q_0: |0>┤ X ├─────■───────────────────────┤ Rx(θ[2]) ├┤ X ├ + ├───┤┌────┴─────┐ ┌───┐└─────┬────┘└───┘ +q_1: |0>┤ X ├┤ Rx(θ[0]) ├─────■──────┤ X ├──────┼────────── + ├───┤└──────────┘┌────┴─────┐└───┘ │ ┌───┐ +q_2: |0>┤ X ├────────────┤ Rx(θ[1]) ├───────────■─────┤ X ├ + └───┘ └──────────┘ └───┘ +``` + +```python +>>> entangler_map = [[0, 3], [0, 2]] # entangle the first and last two-way +>>> two = TwoLocal(4, [], 'cry', entangler_map, reps=1) +>>> circuit = two + two +>>> print(circuit.decompose().draw()) # note, that the parameters are the same! +q_0: ─────■───────────■───────────■───────────■────── + │ │ │ │ +q_1: ─────┼───────────┼───────────┼───────────┼────── + │ ┌────┴─────┐ │ ┌────┴─────┐ +q_2: ─────┼──────┤ Ry(θ[1]) ├─────┼──────┤ Ry(θ[1]) ├ + ┌────┴─────┐└──────────┘┌────┴─────┐└──────────┘ +q_3: ┤ Ry(θ[0]) ├────────────┤ Ry(θ[0]) ├──────────── + └──────────┘ └──────────┘ +``` + +```python +>>> layer_1 = [(0, 1), (0, 2)] +>>> layer_2 = [(1, 2)] +>>> two = TwoLocal(3, 'x', 'cx', [layer_1, layer_2], reps=2, insert_barriers=True) +>>> print(two) + ┌───┐ ░ ░ ┌───┐ ░ ░ ┌───┐ +q_0: ┤ X ├─░───■────■───░─┤ X ├─░───────░─┤ X ├ + ├───┤ ░ ┌─┴─┐ │ ░ ├───┤ ░ ░ ├───┤ +q_1: ┤ X ├─░─┤ X ├──┼───░─┤ X ├─░───■───░─┤ X ├ + ├───┤ ░ └───┘┌─┴─┐ ░ ├───┤ ░ ┌─┴─┐ ░ ├───┤ +q_2: ┤ X ├─░──────┤ X ├─░─┤ X ├─░─┤ X ├─░─┤ X ├ + └───┘ ░ └───┘ ░ └───┘ ░ └───┘ ░ └───┘ +``` + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits of the two-local circuit. +* **rotation\_blocks** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – The gates used in the rotation layer. Can be specified via the name of a gate (e.g. `'ry'`) or the gate type itself (e.g. [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.RYGate")). If only one gate is provided, the gate same gate is applied to each qubit. If a list of gates is provided, all gates are applied to each qubit in the provided order. See the Examples section for more detail. +* **entanglement\_blocks** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – The gates used in the entanglement layer. Can be specified in the same format as `rotation_blocks`. +* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | Callable\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Specifies the entanglement structure. Can be a string (`'full'`, `'linear'`, `'reverse_linear'`, `'circular'` or `'sca'`), a list of integer-pairs specifying the indices of qubits entangled with one another, or a callable returning such a list provided with the index of the entanglement layer. Default to `'full'` entanglement. Note that if `entanglement_blocks = 'cx'`, then `'full'` entanglement provides the same unitary as `'reverse_linear'` but the latter option has fewer entangling gates. See the Examples section for more detail. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Specifies how often a block consisting of a rotation layer and entanglement layer is repeated. +* **skip\_unentangled\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, the single qubit gates are only applied to qubits that are entangled with another qubit. If `False`, the single qubit gates are applied to each qubit in the ansatz. Defaults to `False`. +* **skip\_final\_rotation\_layer** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `False`, a rotation layer is added at the end of the ansatz. If `True`, no rotation layer is added. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The parameterized gates require a parameter to be defined, for which we use instances of [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter"). The name of each parameter will be this specified prefix plus its index. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, barriers are inserted in between each layer. If `False`, no barriers are inserted. Defaults to `False`. +* **initial\_state** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| None*) – A [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object to prepend to the circuit. +* **flatten** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Set this to `True` to output a flat circuit instead of nesting it inside multiple layers of gate objects. By default currently the contents of the output circuit will be wrapped in nested objects for cleaner visualization. However, if you’re using this circuit for anything besides visualization its **strongly** recommended to set this flag to `True` to avoid a large performance overhead for parameter binding. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see [`get_entangler_map()`](#qiskit.circuit.library.TwoLocal.get_entangler_map "qiskit.circuit.library.TwoLocal.get_entangler_map") for more detail on how the format is interpreted. + + + +### entanglement\_blocks + +The blocks in the entanglement layers. + +**Returns** + +The blocks in the entanglement layers. + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of total parameters that can be set to distinct values. + +This does not change when the parameters are bound or exchanged for same parameters, and therefore is different from `num_parameters` which counts the number of unique [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects currently in the circuit. + +**Returns** + +The number of parameters originally available in the circuit. + + + This quantity does not require the circuit to be built yet. + + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + +## Methods + +### get\_entangler\_map + + + +`get_entangler_map(rep_num, block_num, num_block_qubits)` + +Overloading to handle the special case of 1 qubit where the entanglement are ignored. + +**Return type** + +[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.U1Gate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.U1Gate.md new file mode 100644 index 00000000000..5d7b438b452 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.U1Gate.md @@ -0,0 +1,208 @@ +--- +title: U1Gate +description: API reference for qiskit.circuit.library.U1Gate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.U1Gate +--- + +# U1Gate + + + +`qiskit.circuit.library.U1Gate(theta, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u1.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit rotation about the Z axis. + +This is a diagonal gate. It can be implemented virtually in hardware via framechanges (i.e. at zero error and duration). + + + This gate is deprecated. Instead, the following replacements should be used + + $$ + U1(\lambda) = P(\lambda)= U(0,0,\lambda) + $$ + + ```python + circuit = QuantumCircuit(1) + circuit.p(lambda, 0) # or circuit.u(0, 0, lambda) + ``` + + +**Circuit symbol:** + +```python + ┌───────┐ +q_0: ┤ U1(λ) ├ + └───────┘ +``` + +**Matrix Representation:** + +$$ +U1(\lambda) = + \begin{pmatrix} + 1 & 0 \\ + 0 & e^{i\lambda} + \end{pmatrix} +$$ + +**Examples:** + +> $$ +> U1(\lambda = \pi) = Z +> $$ +> +> $$ +> U1(\lambda = \pi/2) = S +> $$ +> +> $$ +> U1(\lambda = \pi/4) = T +> $$ + + + `RZGate`: This gate is equivalent to RZ up to a phase factor. + + > $$ + > U1(\lambda) = e^{i{\lambda}/2} RZ(\lambda) + > $$ + + `U3Gate`: U3 is a generalization of U2 that covers all single-qubit rotations, using two X90 pulses. + + Reference for virtual Z gate implementation: [1612.00858](https://arxiv.org/abs/1612.00858) + + +Create new U1 gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.U1Gate.base_class "qiskit.circuit.library.U1Gate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-U1 gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted U1 gate ($U1(\lambda)^{\dagger} = U1(-\lambda)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.U2Gate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.U2Gate.md new file mode 100644 index 00000000000..c0cd19dcdfc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.U2Gate.md @@ -0,0 +1,187 @@ +--- +title: U2Gate +description: API reference for qiskit.circuit.library.U2Gate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.U2Gate +--- + +# U2Gate + + + +`qiskit.circuit.library.U2Gate(phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u2.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit rotation about the X+Z axis. + +Implemented using one X90 pulse on IBM Quantum systems: + + + This gate is deprecated. Instead, the following replacements should be used + + $$ + U2(\phi, \lambda) = U\left(\frac{\pi}{2}, \phi, \lambda\right) + $$ + + ```python + circuit = QuantumCircuit(1) + circuit.u(pi/2, phi, lambda) + ``` + + +**Circuit symbol:** + +```python + ┌─────────┐ +q_0: ┤ U2(φ,λ) ├ + └─────────┘ +``` + +**Matrix Representation:** + +$$ +U2(\phi, \lambda) = \frac{1}{\sqrt{2}} + \begin{pmatrix} + 1 & -e^{i\lambda} \\ + e^{i\phi} & e^{i(\phi+\lambda)} + \end{pmatrix} +$$ + +**Examples:** + +$$ +U2(\phi,\lambda) = e^{i \frac{\phi + \lambda}{2}}RZ(\phi) +RY\left(\frac{\pi}{2}\right) RZ(\lambda) += e^{- i\frac{\pi}{4}} P\left(\frac{\pi}{2} + \phi\right) +\sqrt{X} P\left(\lambda- \frac{\pi}{2}\right) +$$ + +$$ +U2(0, \pi) = H +$$ + +$$ +U2(0, 0) = RY(\pi/2) +$$ + +$$ +U2(-\pi/2, \pi/2) = RX(\pi/2) +$$ + + + `U3Gate`: U3 is a generalization of U2 that covers all single-qubit rotations, using two X90 pulses. + + +Create new U2 gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.U2Gate.base_class "qiskit.circuit.library.U2Gate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverted U2 gate. + +$U2(\phi, \lambda)^{\dagger} =U2(-\lambda-\pi, -\phi+\pi)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.U3Gate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.U3Gate.md new file mode 100644 index 00000000000..e9f4b5fa741 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.U3Gate.md @@ -0,0 +1,204 @@ +--- +title: U3Gate +description: API reference for qiskit.circuit.library.U3Gate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.U3Gate +--- + +# U3Gate + + + +`qiskit.circuit.library.U3Gate(theta, phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u3.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Generic single-qubit rotation gate with 3 Euler angles. + + + This gate is deprecated. Instead, the following replacements should be used + + $$ + U3(\theta, \phi, \lambda) = U(\theta, \phi, \lambda) + $$ + + ```python + circuit = QuantumCircuit(1) + circuit.u(theta, phi, lambda) + ``` + + +**Circuit symbol:** + +```python + ┌───────────┐ +q_0: ┤ U3(ϴ,φ,λ) ├ + └───────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +U3(\theta, \phi, \lambda) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & -e^{i\lambda}\sin\left(\rotationangle\right) \\ + e^{i\phi}\sin\left(\rotationangle\right) & + e^{i(\phi+\lambda)}\cos\left(\rotationangle\right) + \end{pmatrix} +$$ + + + The matrix representation shown here differs from the [OpenQASM 2.0 specification](https://doi.org/10.48550/arXiv.1707.03429) by a global phase of $e^{i(\phi+\lambda)/2}$. + + +**Examples:** + +$$ +U3(\theta, \phi, \lambda) = e^{-i \frac{\pi + \theta}{2}} P(\phi + \pi) \sqrt{X} +P(\theta + \pi) \sqrt{X} P(\lambda) +$$ + +$$ +U3\left(\theta, -\frac{\pi}{2}, \frac{\pi}{2}\right) = RX(\theta) +$$ + +$$ +U3(\theta, 0, 0) = RY(\theta) +$$ + +Create new U3 gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.U3Gate.base_class "qiskit.circuit.library.U3Gate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-U3 gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted U3 gate. + +$U3(\theta,\phi,\lambda)^{\dagger} =U3(-\theta,-\lambda,-\phi)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UCGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UCGate.md new file mode 100644 index 00000000000..7170576bad6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UCGate.md @@ -0,0 +1,169 @@ +--- +title: UCGate +description: API reference for qiskit.circuit.library.UCGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UCGate +--- + +# UCGate + + + +`qiskit.circuit.library.UCGate(gate_list, up_to_diagonal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/uc.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Uniformly controlled gate (also called multiplexed gate). + +These gates can have several control qubits and a single target qubit. If the k control qubits are in the state $|i\rangle$ (in the computational basis), a single-qubit unitary $U_i$ is applied to the target qubit. + +This gate is represented by a block-diagonal matrix, where each block is a $2\times 2$ unitary, that is + +$$ +\begin{pmatrix} + U_0 & 0 & \cdots & 0 \\ + 0 & U_1 & \cdots & 0 \\ + \vdots & & \ddots & \vdots \\ + 0 & 0 & \cdots & U_{2^{k-1}} +\end{pmatrix}. +$$ + +The decomposition is based on Ref. \[1]. + +**References:** + +**\[1] Bergholm et al., Quantum circuits with uniformly controlled one-qubit gates (2005).** + +[Phys. Rev. A 71, 052330](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.71.052330). + +**Parameters** + +* **gate\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[np.ndarray]*) – List of two qubit unitaries $[U_0, ..., U_{2^{k-1}}]$, where each single-qubit unitary $U_i$ is given as a $2 \times 2$ numpy array. +* **up\_to\_diagonal** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Determines if the gate is implemented up to a diagonal. or if it is decomposed completely (default: False). If the `UCGate` $U$ is decomposed up to a diagonal $D$, this means that the circuit implements a unitary $U'$ such that $D U' = U$. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – in case of bad input to the constructor + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UCGate.base_class "qiskit.circuit.library.UCGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return the inverse. + +This does not re-compute the decomposition for the multiplexer with the inverse of the gates but simply inverts the existing decomposition. + +**Return type** + +[*Gate*](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Uniformly controlled gate parameter has to be an ndarray. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UCPauliRotGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UCPauliRotGate.md new file mode 100644 index 00000000000..f9961b5a124 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UCPauliRotGate.md @@ -0,0 +1,122 @@ +--- +title: UCPauliRotGate +description: API reference for qiskit.circuit.library.UCPauliRotGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UCPauliRotGate +--- + +# UCPauliRotGate + + + +`qiskit.circuit.library.UCPauliRotGate(angle_list, rot_axis)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/uc_pauli_rot.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Uniformly controlled Pauli rotations. + +Implements the [`UCGate`](qiskit.circuit.library.UCGate "qiskit.circuit.library.UCGate") for the special case that all unitaries are Pauli rotations, $U_i = R_P(a_i)$ where $P \in \{X, Y, Z\}$ and $a_i \in \mathbb{R}$ is the rotation angle. + +**Parameters** + +* **angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of rotation angles $[a_0, ..., a_{2^{k-1}}]$. +* **rot\_axis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Rotation axis. Must be either of `"X"`, `"Y"` or `"Z"`. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UCPauliRotGate.base_class "qiskit.circuit.library.UCPauliRotGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UCRXGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UCRXGate.md new file mode 100644 index 00000000000..4ea350c9129 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UCRXGate.md @@ -0,0 +1,121 @@ +--- +title: UCRXGate +description: API reference for qiskit.circuit.library.UCRXGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UCRXGate +--- + +# UCRXGate + + + +`qiskit.circuit.library.UCRXGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/ucrx.py "view source code") + +Bases: [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.generalized_gates.uc_pauli_rot.UCPauliRotGate") + +Uniformly controlled Pauli-X rotations. + +Implements the [`UCGate`](qiskit.circuit.library.UCGate "qiskit.circuit.library.UCGate") for the special case that all unitaries are Pauli-X rotations, $U_i = R_X(a_i)$ where $a_i \in \mathbb{R}$ is the rotation angle. + +**Parameters** + +**angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of rotation angles $[a_0, ..., a_{2^{k-1}}]$. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UCRXGate.base_class "qiskit.circuit.library.UCRXGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UCRYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UCRYGate.md new file mode 100644 index 00000000000..8a1b9e170dd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UCRYGate.md @@ -0,0 +1,121 @@ +--- +title: UCRYGate +description: API reference for qiskit.circuit.library.UCRYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UCRYGate +--- + +# UCRYGate + + + +`qiskit.circuit.library.UCRYGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/ucry.py "view source code") + +Bases: [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.generalized_gates.uc_pauli_rot.UCPauliRotGate") + +Uniformly controlled Pauli-Y rotations. + +Implements the [`UCGate`](qiskit.circuit.library.UCGate "qiskit.circuit.library.UCGate") for the special case that all unitaries are Pauli-Y rotations, $U_i = R_Y(a_i)$ where $a_i \in \mathbb{R}$ is the rotation angle. + +**Parameters** + +**angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of rotation angles $[a_0, ..., a_{2^{k-1}}]$. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UCRYGate.base_class "qiskit.circuit.library.UCRYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UCRZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UCRZGate.md new file mode 100644 index 00000000000..68a6143098a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UCRZGate.md @@ -0,0 +1,121 @@ +--- +title: UCRZGate +description: API reference for qiskit.circuit.library.UCRZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UCRZGate +--- + +# UCRZGate + + + +`qiskit.circuit.library.UCRZGate(angle_list)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/ucrz.py "view source code") + +Bases: [`UCPauliRotGate`](qiskit.circuit.library.UCPauliRotGate "qiskit.circuit.library.generalized_gates.uc_pauli_rot.UCPauliRotGate") + +Uniformly controlled Pauli-Z rotations. + +Implements the [`UCGate`](qiskit.circuit.library.UCGate "qiskit.circuit.library.UCGate") for the special case that all unitaries are Pauli-Z rotations, $U_i = R_Z(a_i)$ where $a_i \in \mathbb{R}$ is the rotation angle. + +**Parameters** + +**angle\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of rotation angles $[a_0, ..., a_{2^{k-1}}]$. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UCRZGate.base_class "qiskit.circuit.library.UCRZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UGate.md new file mode 100644 index 00000000000..422fe3c621d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UGate.md @@ -0,0 +1,187 @@ +--- +title: UGate +description: API reference for qiskit.circuit.library.UGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UGate +--- + +# UGate + + + +`qiskit.circuit.library.UGate(theta, phi, lam, label=None, *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/u.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Generic single-qubit rotation gate with 3 Euler angles. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`u()`](qiskit.circuit.QuantumCircuit#u "qiskit.circuit.QuantumCircuit.u") method. + +**Circuit symbol:** + +```python + ┌──────────┐ +q_0: ┤ U(ϴ,φ,λ) ├ + └──────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +U(\theta, \phi, \lambda) = +\begin{pmatrix} + \cos\left(\rotationangle\right) & -e^{i\lambda}\sin\left(\rotationangle\right) \\ + e^{i\phi}\sin\left(\rotationangle\right) & e^{i(\phi+\lambda)}\cos\left(\rotationangle\right) +\end{pmatrix} +$$ + + + The matrix representation shown here is the same as in the [OpenQASM 3.0 specification](https://openqasm.com/language/gates.html#built-in-gates), which differs from the [OpenQASM 2.0 specification](https://doi.org/10.48550/arXiv.1707.03429) by a global phase of $e^{i(\phi+\lambda)/2}$. + + +**Examples:** + +$$ +U\left(\theta, -\frac{\pi}{2}, \frac{\pi}{2}\right) = RX(\theta) +$$ + +$$ +U(\theta, 0, 0) = RY(\theta) +$$ + +Create new U gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UGate.base_class "qiskit.circuit.library.UGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-U gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted U gate. + +$U(\theta,\phi,\lambda)^{\dagger} =U(-\theta,-\lambda,-\phi)$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryGate.md new file mode 100644 index 00000000000..8b59d6c0cac --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryGate.md @@ -0,0 +1,209 @@ +--- +title: UnitaryGate +description: API reference for qiskit.circuit.library.UnitaryGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UnitaryGate +--- + +# UnitaryGate + + + +`qiskit.circuit.library.UnitaryGate(data, label=None, check_input=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/generalized_gates/unitary.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Class quantum gates specified by a unitary matrix. + +**Example** + +We can create a unitary gate from a unitary matrix then add it to a quantum circuit. The matrix can also be directly applied to the quantum circuit, see [`QuantumCircuit.unitary()`](qiskit.circuit.QuantumCircuit#unitary "qiskit.circuit.QuantumCircuit.unitary"). + +```python +from qiskit import QuantumCircuit +from qiskit.circuit.library import UnitaryGate + +matrix = [[0, 0, 0, 1], + [0, 0, 1, 0], + [1, 0, 0, 0], + [0, 1, 0, 0]] +gate = UnitaryGate(matrix) + +circuit = QuantumCircuit(2) +circuit.append(gate, [0, 1]) +``` + +Create a gate from a numeric unitary matrix. + +**Parameters** + +* **data** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate") *| BaseOperator*) – Unitary operator. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Unitary name for backend \[Default: None]. +* **check\_input** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `False` this asserts the input is known to be unitary and the checking to validate this will be skipped. This should only ever be used if you know the input is unitary, setting this to `False` and passing in a non-unitary matrix will result unexpected behavior and errors. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If input data is not an N-qubit unitary operator. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.UnitaryGate.base_class "qiskit.circuit.library.UnitaryGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the unitary. + +### conjugate + + + +`conjugate()` + +Return the conjugate of the unitary. + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return controlled version of gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of controls to add to gate (default is 1). +* **label** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional gate label. +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The control state in decimal or as a bit string (e.g. `"1011"`). If `None`, use `2**num_ctrl_qubits - 1`. + +**Returns** + +Controlled version of gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return the adjoint of the unitary. + +### transpose + + + +`transpose()` + +Return the transpose of the unitary. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Unitary gate parameter has to be an ndarray. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryOverlap.md b/docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryOverlap.md new file mode 100644 index 00000000000..4fcb29c8820 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.UnitaryOverlap.md @@ -0,0 +1,256 @@ +--- +title: UnitaryOverlap +description: API reference for qiskit.circuit.library.UnitaryOverlap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.UnitaryOverlap +--- + +# UnitaryOverlap + + + +`qiskit.circuit.library.UnitaryOverlap(unitary1, unitary2, prefix1='p1', prefix2='p2')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/overlap.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +Circuit that returns the overlap between two unitaries $U_2^{\dag} U_1$. + +The input quantum circuits must represent unitary operations, since they must be invertible. If the inputs will have parameters, they are replaced by [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector")s with names “p1” (for circuit `unitary1`) and “p2” (for circuit `unitary_2`) in the output circuit. + +This circuit is usually employed in computing the fidelity: + +```python +.. math:: + + \left|\langle 0| U_2^{\dag} U_1|0\rangle\right|^{2} +``` + +by computing the probability of being in the all-zeros bit-string, or equivalently, the expectation value of projector $|0\rangle\langle 0|$. + +Example: + +```python +import numpy as np +from qiskit.circuit.library import EfficientSU2, UnitaryOverlap +from qiskit.primitives import Sampler + +# get two circuit to prepare states of which we comput the overlap +circuit = EfficientSU2(2, reps=1) +unitary1 = circuit.assign_parameters(np.random.random(circuit.num_parameters)) +unitary2 = circuit.assign_parameters(np.random.random(circuit.num_parameters)) + +# create the overlap circuit +overlap = UnitaryOverap(unitary1, unitary2) + +# sample from the overlap +sampler = Sampler(options={"shots": 100}) +result = sampler.run(overlap).result() + +# the fidelity is the probability to measure 0 +fidelity = result.quasi_dists[0].get(0, 0) +``` + +**Parameters** + +* **unitary1** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – Unitary acting on the ket vector. +* **unitary2** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – Unitary whose inverse operates on the bra vector. +* **prefix1** – The name of the parameter vector associated to `unitary1`, if it is parameterized. Defaults to `"p1"`. +* **prefix2** – The name of the parameter vector associated to `unitary2`, if it is parameterized. Defaults to `"p2"`. + +**Raises** + +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Number of qubits in `unitary1` and `unitary2` does not match. +* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – Inputs contain measurements and/or resets. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.VBERippleCarryAdder.md b/docs/api/qiskit/0.46/qiskit.circuit.library.VBERippleCarryAdder.md new file mode 100644 index 00000000000..95cb4888005 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.VBERippleCarryAdder.md @@ -0,0 +1,255 @@ +--- +title: VBERippleCarryAdder +description: API reference for qiskit.circuit.library.VBERippleCarryAdder +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.VBERippleCarryAdder +--- + +# VBERippleCarryAdder + + + +`qiskit.circuit.library.VBERippleCarryAdder(num_state_qubits, kind='full', name='VBERippleCarryAdder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/adders/vbe_ripple_carry_adder.py "view source code") + +Bases: `Adder` + +The VBE ripple carry adder \[1]. + +This circuit performs inplace addition of two equally-sized quantum registers. As an example, a classical adder circuit that performs full addition (i.e. including a carry-in bit) on two 2-qubit sized registers is as follows: + +```python + ┌────────┐ ┌───────────┐┌──────┐ + cin_0: ┤0 ├───────────────────────┤0 ├┤0 ├ + │ │ │ ││ │ + a_0: ┤1 ├───────────────────────┤1 ├┤1 ├ + │ │┌────────┐ ┌──────┐│ ││ Sum │ + a_1: ┤ ├┤1 ├──■──┤1 ├┤ ├┤ ├ + │ ││ │ │ │ ││ ││ │ + b_0: ┤2 Carry ├┤ ├──┼──┤ ├┤2 Carry_dg ├┤2 ├ + │ ││ │┌─┴─┐│ ││ │└──────┘ + b_1: ┤ ├┤2 Carry ├┤ X ├┤2 Sum ├┤ ├──────── + │ ││ │└───┘│ ││ │ + cout_0: ┤ ├┤3 ├─────┤ ├┤ ├──────── + │ ││ │ │ ││ │ +helper_0: ┤3 ├┤0 ├─────┤0 ├┤3 ├──────── + └────────┘└────────┘ └──────┘└───────────┘ +``` + +Here *Carry* and *Sum* gates correspond to the gates introduced in \[1]. *Carry\_dg* correspond to the inverse of the *Carry* gate. Note that in this implementation the input register qubits are ordered as all qubits from the first input register, followed by all qubits from the second input register. This is different ordering as compared to Figure 2 in \[1], which leads to a different drawing of the circuit. + +**References:** + +\[1] Vedral et al., Quantum Networks for Elementary Arithmetic Operations, 1995. [arXiv:quant-ph/9511018](https://arxiv.org/pdf/quant-ph/9511018.pdf) + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The size of the register. +* **kind** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The kind of adder, can be `'full'` for a full adder, `'half'` for a half adder, or `'fixed'` for a fixed-sized adder. A full adder includes both carry-in and carry-out, a half only carry-out, and a fixed-sized adder neither carry-in nor carry-out. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `num_state_qubits` is lower than 1. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of state qubits, i.e. the number of bits in each input register. + +**Returns** + +The number of state qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.WeightedAdder.md b/docs/api/qiskit/0.46/qiskit.circuit.library.WeightedAdder.md new file mode 100644 index 00000000000..e9f59f146c8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.WeightedAdder.md @@ -0,0 +1,251 @@ +--- +title: WeightedAdder +description: API reference for qiskit.circuit.library.WeightedAdder +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.WeightedAdder +--- + +# WeightedAdder + + + +`qiskit.circuit.library.WeightedAdder(num_state_qubits=None, weights=None, name='adder')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/arithmetic/weighted_adder.py "view source code") + +Bases: `BlueprintCircuit` + +A circuit to compute the weighted sum of qubit registers. + +Given $n$ qubit basis states $q_0, \ldots, q_{n-1} \in \{0, 1\}$ and non-negative integer weights $\lambda_0, \ldots, \lambda_{n-1}$, this circuit performs the operation + +$$ +|q_0 \ldots q_{n-1}\rangle |0\rangle_s +\mapsto |q_0 \ldots q_{n-1}\rangle |\sum_{j=0}^{n-1} \lambda_j q_j\rangle_s +$$ + +where $s$ is the number of sum qubits required. This can be computed as + +$$ +s = 1 + \left\lfloor \log_2\left( \sum_{j=0}^{n-1} \lambda_j \right) \right\rfloor +$$ + +or $s = 1$ if the sum of the weights is 0 (then the expression in the logarithm is invalid). + +For qubits in a circuit diagram, the first weight applies to the upper-most qubit. For an example where the state of 4 qubits is added into a sum register, the circuit can be schematically drawn as + +```python + ┌────────┐ + state_0: ┤0 ├ | state_0 * weights[0] + │ │ | + state_1: ┤1 ├ | + state_1 * weights[1] + │ │ | + state_2: ┤2 ├ | + state_2 * weights[2] + │ │ | + state_3: ┤3 ├ | + state_3 * weights[3] + │ │ + sum_0: ┤4 ├ | + │ Adder │ | + sum_1: ┤5 ├ | = sum_0 * 2^0 + sum_1 * 2^1 + sum_2 * 2^2 + │ │ | + sum_2: ┤6 ├ | + │ │ + carry_0: ┤7 ├ + │ │ + carry_1: ┤8 ├ + │ │ +control_0: ┤9 ├ + └────────┘ +``` + +Computes the weighted sum controlled by state qubits. + +**Parameters** + +* **num\_state\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of state qubits. +* **weights** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – List of weights, one for each state qubit. If none are provided they default to 1 for every qubit. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_carry\_qubits + +The number of carry qubits required to compute the sum. + +Note that this is not necessarily equal to the number of ancilla qubits, these can be queried using `num_ancilla_qubits`. + +**Returns** + +The number of carry qubits required to compute the sum. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_control\_qubits + +The number of additional control qubits required. + +Note that the total number of ancilla qubits can be obtained by calling the method `num_ancilla_qubits`. + +**Returns** + +The number of additional control qubits required (0 or 1). + + + +### num\_parameters + + + +### num\_qubits + +Return number of qubits. + + + +### num\_state\_qubits + +The number of qubits to be summed. + +**Returns** + +The number of state qubits. + + + +### num\_sum\_qubits + +The number of sum qubits in the circuit. + +**Returns** + +The number of qubits needed to represent the weighted sum of the qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### weights + +The weights for the qubit states. + +**Returns** + +The weight for the qubit states. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.XGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.XGate.md new file mode 100644 index 00000000000..525f90e33cb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.XGate.md @@ -0,0 +1,191 @@ +--- +title: XGate +description: API reference for qiskit.circuit.library.XGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.XGate +--- + +# XGate + + + +`qiskit.circuit.library.XGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/x.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The single-qubit Pauli-X gate ($\sigma_x$). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`x()`](qiskit.circuit.QuantumCircuit#x "qiskit.circuit.QuantumCircuit.x") method. + +**Matrix Representation:** + +$$ +X = \begin{pmatrix} + 0 & 1 \\ + 1 & 0 + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ X ├ + └───┘ +``` + +Equivalent to a $\pi$ radian rotation about the X axis. + + + A global phase difference exists between the definitions of $RX(\pi)$ and $X$. + + $$ + RX(\pi) = \begin{pmatrix} + 0 & -i \\ + -i & 0 + \end{pmatrix} + = -i X + $$ + + +The gate is equivalent to a classical bit flip. + +$$ +|0\rangle \rightarrow |1\rangle \\ +|1\rangle \rightarrow |0\rangle +$$ + +Create new X gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.XGate.base_class "qiskit.circuit.library.XGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-X gate. + +One control returns a CX gate. Two controls returns a CCX gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted X gate (itself). + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.XOR.md b/docs/api/qiskit/0.46/qiskit.circuit.library.XOR.md new file mode 100644 index 00000000000..b562f42ad8f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.XOR.md @@ -0,0 +1,229 @@ +--- +title: XOR +description: API reference for qiskit.circuit.library.XOR +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.XOR +--- + +# XOR + + + +`qiskit.circuit.library.XOR(num_qubits, amount=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/boolean_logic/quantum_xor.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +An n\_qubit circuit for bitwise xor-ing the input with some integer `amount`. + +The `amount` is xor-ed in bitstring form with the input. + +This circuit can also represent addition by `amount` over the finite field GF(2). + +Return a circuit implementing bitwise xor. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the width of circuit. +* **amount** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – the xor amount in decimal form. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – random seed in case a random xor is requested. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the xor bitstring exceeds available qubits. + +**Reference Circuit:** + +![../\_images/qiskit-circuit-library-XOR-1.png](/images/api/qiskit/0.46/qiskit-circuit-library-XOR-1.png) + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 161` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.XXMinusYYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.XXMinusYYGate.md new file mode 100644 index 00000000000..2d02a88ff8a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.XXMinusYYGate.md @@ -0,0 +1,193 @@ +--- +title: XXMinusYYGate +description: API reference for qiskit.circuit.library.XXMinusYYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.XXMinusYYGate +--- + +# XXMinusYYGate + + + +`qiskit.circuit.library.XXMinusYYGate(theta, beta=0, label='(XX-YY)', *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/xx_minus_yy.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +XX-YY interaction gate. + +A 2-qubit parameterized XX-YY interaction. Its action is to induce a coherent rotation by some angle between $|00\rangle$ and $|11\rangle$. + +**Circuit Symbol:** + +```python + ┌───────────────┐ +q_0: ┤0 ├ + │ (XX-YY)(θ,β) │ +q_1: ┤1 ├ + └───────────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{XX-YY}(\theta, \beta) q_0, q_1 = + RZ_1(\beta) \cdot \exp\left(-i \frac{\theta}{2} \frac{XX-YY}{2}\right) \cdot RZ_1(-\beta) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & 0 & 0 & -i\sin\left(\rotationangle\right)e^{-i\beta} \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + -i\sin\left(\rotationangle\right)e^{i\beta} & 0 & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In the above example we apply the gate on (q\_0, q\_1) which results in adding the (optional) phase defined by $\beta$ on q\_1. Instead, if we apply it on (q\_1, q\_0), the phase is added on q\_0. If $\beta$ is set to its default value of $0$, the gate is equivalent in big and little endian. + + ```python + ┌───────────────┐ + q_0: ┤1 ├ + │ (XX-YY)(θ,β) │ + q_1: ┤0 ├ + └───────────────┘ + ``` + + $$ + \newcommand{\rotationangle}{\frac{\theta}{2}} + + R_{XX-YY}(\theta, \beta) q_1, q_0 = + RZ_0(\beta) \cdot \exp\left(-i \frac{\theta}{2} \frac{XX-YY}{2}\right) \cdot RZ_0(-\beta) = + \begin{pmatrix} + \cos\left(\rotationangle\right) & 0 & 0 & -i\sin\left(\rotationangle\right)e^{i\beta} \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + -i\sin\left(\rotationangle\right)e^{-i\beta} & 0 & 0 & \cos\left(\rotationangle\right) + \end{pmatrix} + $$ + + +Create new XX-YY gate. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rotation angle. +* **beta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The phase angle. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The label of the gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.XXMinusYYGate.base_class "qiskit.circuit.library.XXMinusYYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Inverse gate. + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.XXPlusYYGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.XXPlusYYGate.md new file mode 100644 index 00000000000..43752c4f975 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.XXPlusYYGate.md @@ -0,0 +1,193 @@ +--- +title: XXPlusYYGate +description: API reference for qiskit.circuit.library.XXPlusYYGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.XXPlusYYGate +--- + +# XXPlusYYGate + + + +`qiskit.circuit.library.XXPlusYYGate(theta, beta=0, label='(XX+YY)', *, duration=None, unit='dt')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/xx_plus_yy.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +XX+YY interaction gate. + +A 2-qubit parameterized XX+YY interaction, also known as an XY gate. Its action is to induce a coherent rotation by some angle between $|01\rangle$ and $|10\rangle$. + +**Circuit Symbol:** + +```python + ┌───────────────┐ +q_0: ┤0 ├ + │ (XX+YY)(θ,β) │ +q_1: ┤1 ├ + └───────────────┘ +``` + +**Matrix Representation:** + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{XX+YY}(\theta, \beta)\ q_0, q_1 = + RZ_0(-\beta) \cdot \exp\left(-i \frac{\theta}{2} \frac{XX+YY}{2}\right) \cdot RZ_0(\beta) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right)e^{-i\beta} & 0 \\ + 0 & -i\sin\left(\rotationangle\right)e^{i\beta} & \cos\left(\rotationangle\right) & 0 \\ + 0 & 0 & 0 & 1 + \end{pmatrix} +$$ + + + In Qiskit’s convention, higher qubit indices are more significant (little endian convention). In the above example we apply the gate on (q\_0, q\_1) which results in adding the (optional) phase defined by $\beta$ on q\_0. Instead, if we apply it on (q\_1, q\_0), the phase is added on q\_1. If $\beta$ is set to its default value of $0$, the gate is equivalent in big and little endian. + + ```python + ┌───────────────┐ + q_0: ┤1 ├ + │ (XX+YY)(θ,β) │ + q_1: ┤0 ├ + └───────────────┘ + ``` + + +$$ +\newcommand{\rotationangle}{\frac{\theta}{2}} + +R_{XX+YY}(\theta, \beta)\ q_0, q_1 = + RZ_1(-\beta) \cdot \exp\left(-i \frac{\theta}{2} \frac{XX+YY}{2}\right) \cdot RZ_1(\beta) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right)e^{i\beta} & 0 \\ + 0 & -i\sin\left(\rotationangle\right)e^{-i\beta} & \cos\left(\rotationangle\right) & 0 \\ + 0 & 0 & 0 & 1 + \end{pmatrix} +$$ + +Create new XX+YY gate. + +**Parameters** + +* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The rotation angle. +* **beta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The phase angle. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The label of the gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.XXPlusYYGate.base_class "qiskit.circuit.library.XXPlusYYGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### inverse + + + +`inverse()` + +Return inverse XX+YY gate (i.e. with the negative rotation angle and same phase angle). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.YGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.YGate.md new file mode 100644 index 00000000000..cc275fc50c0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.YGate.md @@ -0,0 +1,191 @@ +--- +title: YGate +description: API reference for qiskit.circuit.library.YGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.YGate +--- + +# YGate + + + +`qiskit.circuit.library.YGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/y.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The single-qubit Pauli-Y gate ($\sigma_y$). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`y()`](qiskit.circuit.QuantumCircuit#y "qiskit.circuit.QuantumCircuit.y") method. + +**Matrix Representation:** + +$$ +Y = \begin{pmatrix} + 0 & -i \\ + i & 0 + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ Y ├ + └───┘ +``` + +Equivalent to a $\pi$ radian rotation about the Y axis. + + + A global phase difference exists between the definitions of $RY(\pi)$ and $Y$. + + $$ + RY(\pi) = \begin{pmatrix} + 0 & -1 \\ + 1 & 0 + \end{pmatrix} + = -i Y + $$ + + +The gate is equivalent to a bit and phase flip. + +$$ +|0\rangle \rightarrow i|1\rangle \\ +|1\rangle \rightarrow -i|0\rangle +$$ + +Create new Y gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.YGate.base_class "qiskit.circuit.library.YGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-Y gate. + +One control returns a CY gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted Y gate ($Y^{\dagger} = Y$) + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.ZFeatureMap.md b/docs/api/qiskit/0.46/qiskit.circuit.library.ZFeatureMap.md new file mode 100644 index 00000000000..c7ba5263343 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.ZFeatureMap.md @@ -0,0 +1,367 @@ +--- +title: ZFeatureMap +description: API reference for qiskit.circuit.library.ZFeatureMap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.ZFeatureMap +--- + +# ZFeatureMap + + + +`qiskit.circuit.library.ZFeatureMap(feature_dimension, reps=2, data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/data_preparation/z_feature_map.py "view source code") + +Bases: [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.data_preparation.pauli_feature_map.PauliFeatureMap") + +The first order Pauli Z-evolution circuit. + +On 3 qubits and with 2 repetitions the circuit is represented by: + +```python +┌───┐┌──────────────┐┌───┐┌──────────────┐ +┤ H ├┤ U1(2.0*x[0]) ├┤ H ├┤ U1(2.0*x[0]) ├ +├───┤├──────────────┤├───┤├──────────────┤ +┤ H ├┤ U1(2.0*x[1]) ├┤ H ├┤ U1(2.0*x[1]) ├ +├───┤├──────────────┤├───┤├──────────────┤ +┤ H ├┤ U1(2.0*x[2]) ├┤ H ├┤ U1(2.0*x[2]) ├ +└───┘└──────────────┘└───┘└──────────────┘ +``` + +This is a sub-class of [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.PauliFeatureMap") where the Pauli strings are fixed as \[‘Z’]. As a result the first order expansion will be a circuit without entangling gates. + +**Examples** + +```python +>>> prep = ZFeatureMap(3, reps=3, insert_barriers=True) +>>> print(prep) + ┌───┐ ░ ┌──────────────┐ ░ ┌───┐ ░ ┌──────────────┐ ░ ┌───┐ ░ ┌──────────────┐ +q_0: ┤ H ├─░─┤ U1(2.0*x[0]) ├─░─┤ H ├─░─┤ U1(2.0*x[0]) ├─░─┤ H ├─░─┤ U1(2.0*x[0]) ├ + ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤ +q_1: ┤ H ├─░─┤ U1(2.0*x[1]) ├─░─┤ H ├─░─┤ U1(2.0*x[1]) ├─░─┤ H ├─░─┤ U1(2.0*x[1]) ├ + ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤ ░ ├───┤ ░ ├──────────────┤ +q_2: ┤ H ├─░─┤ U1(2.0*x[2]) ├─░─┤ H ├─░─┤ U1(2.0*x[2]) ├─░─┤ H ├─░─┤ U1(2.0*x[2]) ├ + └───┘ ░ └──────────────┘ ░ └───┘ ░ └──────────────┘ ░ └───┘ ░ └──────────────┘ +``` + +```python +>>> data_map = lambda x: x[0]*x[0] + 1 # note: input is an array +>>> prep = ZFeatureMap(3, reps=1, data_map_func=data_map) +>>> print(prep) + ┌───┐┌───────────────────────┐ +q_0: ┤ H ├┤ U1(2.0*x[0]**2 + 2.0) ├ + ├───┤├───────────────────────┤ +q_1: ┤ H ├┤ U1(2.0*x[1]**2 + 2.0) ├ + ├───┤├───────────────────────┤ +q_2: ┤ H ├┤ U1(2.0*x[2]**2 + 2.0) ├ + └───┘└───────────────────────┘ +``` + +```python +>>> classifier = ZFeatureMap(3, reps=1) + RY(3, reps=1) +>>> print(classifier) + ┌───┐┌──────────────┐┌──────────┐ ┌──────────┐ +q_0: ┤ H ├┤ U1(2.0*x[0]) ├┤ RY(θ[0]) ├─■──■─┤ RY(θ[3]) ├──────────── + ├───┤├──────────────┤├──────────┤ │ │ └──────────┘┌──────────┐ +q_1: ┤ H ├┤ U1(2.0*x[1]) ├┤ RY(θ[1]) ├─■──┼──────■──────┤ RY(θ[4]) ├ + ├───┤├──────────────┤├──────────┤ │ │ ├──────────┤ +q_2: ┤ H ├┤ U1(2.0*x[2]) ├┤ RY(θ[2]) ├────■──────■──────┤ RY(θ[5]) ├ + └───┘└──────────────┘└──────────┘ └──────────┘ +``` + +Create a new first-order Pauli-Z expansion circuit. + +**Parameters** + +* **feature\_dimension** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of features +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of repeated circuits. Defaults to 2, has a minimum value of 1. +* **data\_map\_func** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A mapping function for data x which can be supplied to override the default mapping from `self_product()`. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The prefix used if default parameters are generated. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted in between the evolution instructions and hadamard layers. + +## Attributes + + + +### alpha + +The Pauli rotation factor (alpha). + +**Returns** + +The Pauli rotation factor. + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### feature\_dimension + +Returns the feature dimension (which is equal to the number of qubits). + +**Returns** + +The feature dimension of this feature map. + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 163` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of distinct parameters. + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### paulis + +The Pauli strings used in the entanglement of the qubits. + +**Returns** + +The Pauli strings as list. + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.ZGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.ZGate.md new file mode 100644 index 00000000000..fa9f5ea4899 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.ZGate.md @@ -0,0 +1,199 @@ +--- +title: ZGate +description: API reference for qiskit.circuit.library.ZGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.ZGate +--- + +# ZGate + + + +`qiskit.circuit.library.ZGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/z.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +The single-qubit Pauli-Z gate ($\sigma_z$). + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`z()`](qiskit.circuit.QuantumCircuit#z "qiskit.circuit.QuantumCircuit.z") method. + +**Matrix Representation:** + +$$ +Z = \begin{pmatrix} + 1 & 0 \\ + 0 & -1 + \end{pmatrix} +$$ + +**Circuit symbol:** + +```python + ┌───┐ +q_0: ┤ Z ├ + └───┘ +``` + +Equivalent to a $\pi$ radian rotation about the Z axis. + + + A global phase difference exists between the definitions of $RZ(\pi)$ and $Z$. + + $$ + RZ(\pi) = \begin{pmatrix} + -i & 0 \\ + 0 & i + \end{pmatrix} + = -i Z + $$ + + +The gate is equivalent to a phase flip. + +$$ +|0\rangle \rightarrow |0\rangle \\ +|1\rangle \rightarrow -|1\rangle +$$ + +Create new Z gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.ZGate.base_class "qiskit.circuit.library.ZGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return a (multi-)controlled-Z gate. + +One control returns a CZ gate. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of control qubits. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – An optional label for the gate \[Default: None] +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or None*) – control state expressed as integer, string (e.g. ‘110’), or None. If None, use all 1s. + +**Returns** + +controlled version of this gate. + +**Return type** + +[ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +### inverse + + + +`inverse()` + +Return inverted Z gate (itself). + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.ZZFeatureMap.md b/docs/api/qiskit/0.46/qiskit.circuit.library.ZZFeatureMap.md new file mode 100644 index 00000000000..ab8b04d733d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.ZZFeatureMap.md @@ -0,0 +1,372 @@ +--- +title: ZZFeatureMap +description: API reference for qiskit.circuit.library.ZZFeatureMap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.ZZFeatureMap +--- + +# ZZFeatureMap + + + +`qiskit.circuit.library.ZZFeatureMap(feature_dimension, reps=2, entanglement='full', data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZZFeatureMap')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/data_preparation/zz_feature_map.py "view source code") + +Bases: [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.data_preparation.pauli_feature_map.PauliFeatureMap") + +Second-order Pauli-Z evolution circuit. + +For 3 qubits and 1 repetition and linear entanglement the circuit is represented by: + +```python +┌───┐┌─────────────────┐ +┤ H ├┤ U1(2.0*φ(x[0])) ├──■────────────────────────────■──────────────────────────────────── +├───┤├─────────────────┤┌─┴─┐┌──────────────────────┐┌─┴─┐ +┤ H ├┤ U1(2.0*φ(x[1])) ├┤ X ├┤ U1(2.0*φ(x[0],x[1])) ├┤ X ├──■────────────────────────────■── +├───┤├─────────────────┤└───┘└──────────────────────┘└───┘┌─┴─┐┌──────────────────────┐┌─┴─┐ +┤ H ├┤ U1(2.0*φ(x[2])) ├──────────────────────────────────┤ X ├┤ U1(2.0*φ(x[1],x[2])) ├┤ X ├ +└───┘└─────────────────┘ └───┘└──────────────────────┘└───┘ +``` + +where $\varphi$ is a classical non-linear function, which defaults to $\varphi(x) = x$ if and $\varphi(x,y) = (\pi - x)(\pi - y)$. + +**Examples** + +```python +>>> from qiskit.circuit.library import ZZFeatureMap +>>> prep = ZZFeatureMap(2, reps=1) +>>> print(prep) + ┌───┐┌──────────────┐ +q_0: ┤ H ├┤ U1(2.0*x[0]) ├──■───────────────────────────────────────■── + ├───┤├──────────────┤┌─┴─┐┌─────────────────────────────────┐┌─┴─┐ +q_1: ┤ H ├┤ U1(2.0*x[1]) ├┤ X ├┤ U1(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├ + └───┘└──────────────┘└───┘└─────────────────────────────────┘└───┘ +``` + +```python +>>> from qiskit.circuit.library import EfficientSU2 +>>> classifier = ZZFeatureMap(3) + EfficientSU2(3) +>>> classifier.num_parameters +15 +>>> classifier.parameters # 'x' for the data preparation, 'θ' for the SU2 parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(θ[0]), + ParameterVectorElement(θ[1]), ParameterVectorElement(θ[2]), + ParameterVectorElement(θ[3]), ParameterVectorElement(θ[4]), + ParameterVectorElement(θ[5]), ParameterVectorElement(θ[6]), + ParameterVectorElement(θ[7]), ParameterVectorElement(θ[8]), + ParameterVectorElement(θ[9]), ParameterVectorElement(θ[10]), + ParameterVectorElement(θ[11]), ParameterVectorElement(θ[12]), + ParameterVectorElement(θ[13]), ParameterVectorElement(θ[14]), + ParameterVectorElement(θ[15]), ParameterVectorElement(θ[16]), + ParameterVectorElement(θ[17]), ParameterVectorElement(θ[18]), + ParameterVectorElement(θ[19]), ParameterVectorElement(θ[20]), + ParameterVectorElement(θ[21]), ParameterVectorElement(θ[22]), + ParameterVectorElement(θ[23]) +]) +>>> classifier.count_ops() +OrderedDict([('ZZFeatureMap', 1), ('EfficientSU2', 1)]) +``` + +Create a new second-order Pauli-Z expansion. + +**Parameters** + +* **feature\_dimension** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of features. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of repeated circuits, has a min. value of 1. +* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] |* [*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – Specifies the entanglement structure. Refer to [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.NLocal") for detail. +* **data\_map\_func** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A mapping function for data x. +* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The prefix used if default parameters are generated. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, barriers are inserted in between the evolution instructions and hadamard layers. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the feature dimension is smaller than 2. + +## Attributes + + + +### alpha + +The Pauli rotation factor (alpha). + +**Returns** + +The Pauli rotation factor. + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + + + +### entanglement + +Get the entanglement strategy. + +**Returns** + +The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted. + + + +### entanglement\_blocks + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### feature\_dimension + +Returns the feature dimension (which is equal to the number of qubits). + +**Returns** + +The feature dimension of this feature map. + + + +### flatten + +Returns whether the circuit is wrapped in nested gates/instructions or flattened. + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### initial\_state + +Return the initial state that is added in front of the n-local circuit. + +**Returns** + +The initial state. + + + +### insert\_barriers + +If barriers are inserted in between the layers or not. + +**Returns** + +`True`, if barriers are inserted in between the layers, `False` if not. + + + +### instances + +`= 163` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_layers + +Return the number of layers in the n-local circuit. + +**Returns** + +The number of layers in the circuit. + + + +### num\_parameters + + + +### num\_parameters\_settable + +The number of distinct parameters. + + + +### num\_qubits + +Returns the number of qubits in this circuit. + +**Returns** + +The number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### ordered\_parameters + +The parameters used in the underlying circuit. + +This includes float values and duplicates. + +**Examples** + +```python +>>> # prepare circuit ... +>>> print(nlocal) + ┌───────┐┌──────────┐┌──────────┐┌──────────┐ +q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├ + └───────┘└──────────┘└──────────┘└──────────┘ +>>> nlocal.parameters +{Parameter(θ[1]), Parameter(θ[3])} +>>> nlocal.ordered_parameters +[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])] +``` + +**Returns** + +The parameters objects used in the circuit. + + + +### parameter\_bounds + +The parameter bounds for the unbound parameters in the circuit. + +**Returns** + +A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded. + + + +### parameters + + + +### paulis + +The Pauli strings used in the entanglement of the qubits. + +**Returns** + +The Pauli strings as list. + + + +### preferred\_init\_points + +The initial points for the parameters. Can be stored as initial guess in optimization. + +**Returns** + +The initial values for the parameters, or None, if none have been set. + + + +### prefix + +`= 'circuit'` + + + +### qregs + +`list[QuantumRegister]` + +A list of the quantum registers associated with the circuit. + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### reps + +The number of times rotation and entanglement block are repeated. + +**Returns** + +The number of repetitions. + + + +### rotation\_blocks + +The blocks in the rotation layers. + +**Returns** + +The blocks in the rotation layers. + diff --git a/docs/api/qiskit/0.46/qiskit.circuit.library.iSwapGate.md b/docs/api/qiskit/0.46/qiskit.circuit.library.iSwapGate.md new file mode 100644 index 00000000000..877beaf25b4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.circuit.library.iSwapGate.md @@ -0,0 +1,180 @@ +--- +title: iSwapGate +description: API reference for qiskit.circuit.library.iSwapGate +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.circuit.library.iSwapGate +--- + +# iSwapGate + + + +`qiskit.circuit.library.iSwapGate(*args, _force_mutable=False, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/circuit/library/standard_gates/iswap.py "view source code") + +Bases: [`SingletonGate`](circuit_singleton#qiskit.circuit.singleton.SingletonGate "qiskit.circuit.singleton.SingletonGate") + +iSWAP gate. + +A 2-qubit XX+YY interaction. This is a Clifford and symmetric gate. Its action is to swap two qubit states and phase the $|01\rangle$ and $|10\rangle$ amplitudes by i. + +Can be applied to a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with the [`iswap()`](qiskit.circuit.QuantumCircuit#iswap "qiskit.circuit.QuantumCircuit.iswap") method. + +**Circuit Symbol:** + +```python +q_0: ─⨂─ + │ +q_1: ─⨂─ +``` + +**Reference Implementation:** + +```python + ┌───┐┌───┐ ┌───┐ +q_0: ┤ S ├┤ H ├──■──┤ X ├───── + ├───┤└───┘┌─┴─┐└─┬─┘┌───┐ +q_1: ┤ S ├─────┤ X ├──■──┤ H ├ + └───┘ └───┘ └───┘ +``` + +**Matrix Representation:** + +$$ +iSWAP = R_{XX+YY}\left(-\frac{\pi}{2}\right) + = \exp\left(i \frac{\pi}{4} \left(X{\otimes}X+Y{\otimes}Y\right)\right) = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 0 & i & 0 \\ + 0 & i & 0 & 0 \\ + 0 & 0 & 0 & 1 + \end{pmatrix} +$$ + +This gate is equivalent to a SWAP up to a diagonal. + +$$ +iSWAP = + \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 1 & 0 & 0 \\ + 0 & 0 & 0 & 1 + \end{pmatrix} +. \begin{pmatrix} + 1 & 0 & 0 & 0 \\ + 0 & i & 0 & 0 \\ + 0 & 0 & i & 0 \\ + 0 & 0 & 0 & 1 + \end{pmatrix} +$$ + +Create new iSwap gate. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.circuit.library.iSwapGate.base_class "qiskit.circuit.library.iSwapGate.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### power + + + +`power(exponent)` + +Raise gate to a power. + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGCircuit.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGCircuit.md new file mode 100644 index 00000000000..19f6d1074ea --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGCircuit.md @@ -0,0 +1,1026 @@ +--- +title: DAGCircuit +description: API reference for qiskit.dagcircuit.DAGCircuit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGCircuit +--- + +# DAGCircuit + + + +`qiskit.dagcircuit.DAGCircuit`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagcircuit.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Quantum circuit as a directed acyclic graph. + +There are 3 types of nodes in the graph: inputs, outputs, and operations. The nodes are connected by directed edges that correspond to qubits and bits. + +Create an empty circuit. + +## Attributes + + + +### calibrations + +Return calibration dictionary. + +**The custom pulse definition of a given gate is of the form** + +\{‘gate\_name’: \{(qubits, params): schedule}} + + + +### global\_phase + +Return the global phase of the circuit. + + + +### node\_counter + +Returns the number of nodes in the dag. + + + +### wires + +Return a list of the wires in order. + +## Methods + +### add\_calibration + + + +`add_calibration(gate, qubits, schedule, params=None)` + +Register a low-level, custom pulse definition for the given gate. + +**Parameters** + +* **gate** (*Union\[*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Gate information. +* **qubits** (*Union\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, Tuple\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – List of qubits to be measured. +* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule")) – Schedule information. +* **params** (*Optional\[List\[Union\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*]]]*) – A list of parameters. + +**Raises** + +[**Exception**](https://docs.python.org/3/library/exceptions.html#Exception "(in Python v3.12)") – if the gate is of type string and params is None. + +### add\_clbits + + + +`add_clbits(clbits)` + +Add individual clbit wires. + +### add\_creg + + + +`add_creg(creg)` + +Add all wires in a classical register. + +### add\_qreg + + + +`add_qreg(qreg)` + +Add all wires in a quantum register. + +### add\_qubits + + + +`add_qubits(qubits)` + +Add individual qubit wires. + +### ancestors + + + +`ancestors(node)` + +Returns set of the ancestors of a node as DAGOpNodes and DAGInNodes. + +### apply\_operation\_back + + + +`apply_operation_back(op, qargs=(), cargs=(), *, check=True)` + +Apply an operation to the output of the circuit. + +**Parameters** + +* **op** ([*qiskit.circuit.Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – the operation associated with the DAG node +* **qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – qubits that op will be applied to +* **cargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – cbits that op will be applied to +* **check** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` (default), this function will enforce that the [`DAGCircuit`](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") data-structure invariants are maintained (all `qargs` are [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit")s, all are in the DAG, etc). If `False`, the caller *must* uphold these invariants itself, but the cost of several checks will be skipped. This is most useful when building a new DAG from a source of known-good nodes. + +**Returns** + +the node for the op that was added to the dag + +**Return type** + +[DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode") + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if a leaf node is connected to multiple outputs + +### apply\_operation\_front + + + +`apply_operation_front(op, qargs=(), cargs=(), *, check=True)` + +Apply an operation to the input of the circuit. + +**Parameters** + +* **op** ([*qiskit.circuit.Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – the operation associated with the DAG node +* **qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – qubits that op will be applied to +* **cargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – cbits that op will be applied to +* **check** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` (default), this function will enforce that the [`DAGCircuit`](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") data-structure invariants are maintained (all `qargs` are [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit")s, all are in the DAG, etc). If `False`, the caller *must* uphold these invariants itself, but the cost of several checks will be skipped. This is most useful when building a new DAG from a source of known-good nodes. + +**Returns** + +the node for the op that was added to the dag + +**Return type** + +[DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode") + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if initial nodes connected to multiple out edges + +### bfs\_successors + + + +`bfs_successors(node)` + +Returns an iterator of tuples of (DAGNode, \[DAGNodes]) where the DAGNode is the current node and \[DAGNode] is its successors in BFS order. + +### classical\_predecessors + + + +`classical_predecessors(node)` + +Returns iterator of the predecessors of a node that are connected by a classical edge as DAGOpNodes and DAGInNodes. + +### classical\_successors + + + +`classical_successors(node)` + +Returns iterator of the successors of a node that are connected by a classical edge as DAGOpNodes and DAGInNodes. + +### collect\_1q\_runs + + + +`collect_1q_runs()` + +Return a set of non-conditional runs of 1q “op” nodes. + +### collect\_2q\_runs + + + +`collect_2q_runs()` + +Return a set of non-conditional runs of 2q “op” nodes. + +### collect\_runs + + + +`collect_runs(namelist)` + +Return a set of non-conditional runs of “op” nodes with the given names. + +For example, “… h q\[0]; cx q\[0],q\[1]; cx q\[0],q\[1]; h q\[1]; ..” would produce the tuple of cx nodes as an element of the set returned from a call to collect\_runs(\[“cx”]). If instead the cx nodes were “cx q\[0],q\[1]; cx q\[1],q\[0];”, the method would still return the pair in a tuple. The namelist can contain names that are not in the circuit’s basis. + +Nodes must have only one successor to continue the run. + +### compose + + + +`compose(other, qubits=None, clbits=None, front=False, inplace=True)` + +Compose the `other` circuit onto the output of this circuit. + +A subset of input wires of `other` are mapped to a subset of output wires of this circuit. + +`other` can be narrower or of equal width to `self`. + +**Parameters** + +* **other** ([*DAGCircuit*](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – circuit to compose with self +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – qubits of self to compose onto. +* **clbits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – clbits of self to compose onto. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, front composition will be performed (not implemented yet) +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, modify the object. Otherwise return composed circuit. + +**Returns** + +the composed dag (returns None if inplace==True). + +**Return type** + +[DAGCircuit](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if `other` is wider or there are duplicate edge mappings. + +### copy\_empty\_like + + + +`copy_empty_like()` + +Return a copy of self with the same structure but empty. + +**That structure includes:** + +* name and other metadata +* global phase +* duration +* all the qubits and clbits, including the registers. + +**Returns** + +An empty copy of self. + +**Return type** + +[DAGCircuit](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### count\_ops + + + +`count_ops(*, recurse=True)` + +Count the occurrences of operation names. + +**Parameters** + +**recurse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True` (default), then recurse into control-flow operations. In all cases, this counts only the number of times the operation appears in any possible block; both branches of if-elses are counted, and for- and while-loop blocks are only counted once. + +**Returns** + +a mapping of operation names to the number of times it appears. + +**Return type** + +Mapping\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### count\_ops\_longest\_path + + + +`count_ops_longest_path()` + +Count the occurrences of operation names on the longest path. + +Returns a dictionary of counts keyed on the operation name. + +### depth + + + +`depth(*, recurse=False)` + +Return the circuit depth. If there is control flow present, this count may only be an estimate, as the complete control-flow path cannot be statically known. + +**Parameters** + +**recurse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True`, then recurse into control-flow operations. For loops with known-length iterators are counted as if the loop had been manually unrolled (*i.e.* with each iteration of the loop body written out explicitly). If-else blocks take the longer case of the two branches. While loops are counted as if the loop body runs once only. Defaults to `False` and raises [`DAGCircuitError`](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") if any control flow is present, to avoid silently returning a nonsensical number. + +**Returns** + +the circuit depth + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +**Raises** + +* [**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if not a directed acyclic graph +* [**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if unknown control flow is present in a recursive call, or any control flow is present in a non-recursive call. + +### descendants + + + +`descendants(node)` + +Returns set of the descendants of a node as DAGOpNodes and DAGOutNodes. + +### draw + + + +`draw(scale=0.7, filename=None, style='color')` + +Draws the dag circuit. + +This function needs [Graphviz](https://www.graphviz.org/) to be installed. Graphviz is not a python package and can’t be pip installed (the `graphviz` package on PyPI is a Python interface library for Graphviz and does not actually install Graphviz). You can refer to [the Graphviz documentation](https://www.graphviz.org/download/) on how to install it. + +**Parameters** + +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – scaling factor +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to (format inferred from name) +* **style** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – ‘plain’: B\&W graph; ‘color’ (default): color input/output/op nodes + +**Returns** + +if in Jupyter notebook and not saving to file, otherwise None. + +**Return type** + +Ipython.display.Image + +### edges + + + +`edges(nodes=None)` + +Iterator for edge values and source and dest node + +This works by returning the output edges from the specified nodes. If no nodes are specified all edges from the graph are returned. + +**Parameters** + +**nodes** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*, or* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")*|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*, or* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – Either a list of nodes or a single input node. If none is specified, all edges are returned from the graph. + +**Yields** + +*edge* – + +**the edge in the same format as out\_edges the tuple** + +(source node, destination node, edge data) + +### find\_bit + + + +`find_bit(bit)` + +Finds locations in the circuit, by mapping the Qubit and Clbit to positional index BitLocations is defined as: BitLocations = namedtuple(“BitLocations”, (“index”, “registers”)) + +**Parameters** + +**bit** ([*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")) – The bit to locate. + +**Returns** + +**A 2-tuple. The first element (`index`)** + +contains the index at which the `Bit` can be found (in either `qubits`, `clbits`, depending on its type). The second element (`registers`) is a list of `(register, index)` pairs with an entry for each `Register` in the circuit which contains the `Bit` (and the index in the `Register` at which it can be found). + +**Return type** + +namedtuple(int, List\[Tuple(Register, int)]) + +**Raises:** + +DAGCircuitError: If the supplied `Bit` was of an unknown type. DAGCircuitError: If the supplied `Bit` could not be found on the circuit. + +### front\_layer + + + +`front_layer()` + +Return a list of op nodes in the first layer of this dag. + +### gate\_nodes + + + +`gate_nodes()` + +Get the list of gate nodes in the dag. + +**Returns** + +the list of DAGOpNodes that represent gates. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")] + +### has\_calibration\_for + + + +`has_calibration_for(node)` + +Return True if the dag has a calibration defined for the node operation. In this case, the operation does not need to be translated to the device basis. + +### idle\_wires + + + +`idle_wires(ignore=None)` + +Return idle wires. + +**Parameters** + +**ignore** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*)*) – List of node names to ignore. Default: \[] + +**Yields** + +*Bit* – Bit in idle wire. + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – If the DAG is invalid + +### is\_predecessor + + + +`is_predecessor(node, node_pred)` + +Checks if a second node is in the predecessors of node. + +### is\_successor + + + +`is_successor(node, node_succ)` + +Checks if a second node is in the successors of node. + +### layers + + + +`layers()` + +Yield a shallow view on a layer of this DAGCircuit for all d layers of this circuit. + +A layer is a circuit whose gates act on disjoint qubits, i.e., a layer has depth 1. The total number of layers equals the circuit depth d. The layers are indexed from 0 to d-1 with the earliest layer at index 0. The layers are constructed using a greedy algorithm. Each returned layer is a dict containing \{“graph”: circuit graph, “partition”: list of qubit lists}. + +The returned layer contains new (but semantically equivalent) DAGOpNodes, DAGInNodes, and DAGOutNodes. These are not the same as nodes of the original dag, but are equivalent via DAGNode.semantic\_eq(node1, node2). + +TODO: Gates that use the same cbits will end up in different layers as this is currently implemented. This may not be the desired behavior. + +### longest\_path + + + +`longest_path()` + +Returns the longest path in the dag as a list of DAGOpNodes, DAGInNodes, and DAGOutNodes. + +### multi\_qubit\_ops + + + +`multi_qubit_ops()` + +Get list of 3+ qubit operations. Ignore directives like snapshot and barrier. + +### multigraph\_layers + + + +`multigraph_layers()` + +Yield layers of the multigraph. + +### named\_nodes + + + +`named_nodes(*names)` + +Get the set of “op” nodes with the given name. + +### node + + + +`node(node_id)` + +Get the node in the dag. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Node identifier. + +**Returns** + +the node. + +**Return type** + +node + +### nodes + + + +`nodes()` + +Iterator for node values. + +**Yields** + +*node* – the node. + +### nodes\_on\_wire + + + +`nodes_on_wire(wire, only_ops=False)` + +Iterator for nodes that affect a given wire. + +**Parameters** + +* **wire** ([*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")) – the wire to be looked at. +* **only\_ops** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if only the ops nodes are wanted; otherwise, all nodes are returned. + +**Yields** + +*Iterator* – the successive nodes on the given wire + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if the given wire doesn’t exist in the DAG + +### num\_clbits + + + +`num_clbits()` + +Return the total number of classical bits used by the circuit. + +### num\_qubits + + + +`num_qubits()` + +Return the total number of qubits used by the circuit. num\_qubits() replaces former use of width(). DAGCircuit.width() now returns qubits + clbits for consistency with Circuit.width() \[qiskit-terra #2564]. + +### num\_tensor\_factors + + + +`num_tensor_factors()` + +Compute how many components the circuit can decompose into. + +### op\_nodes + + + +`op_nodes(op=None, include_directives=True)` + +Get the list of “op” nodes in the dag. + +**Parameters** + +* **op** ([*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")) – [`qiskit.circuit.Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") subclass op nodes to return. If None, return all op nodes. +* **include\_directives** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – include barrier, snapshot etc. + +**Returns** + +the list of node ids containing the given op. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")] + +### predecessors + + + +`predecessors(node)` + +Returns iterator of the predecessors of a node as DAGOpNodes and DAGInNodes. + +### properties + + + +`properties()` + +Return a dictionary of circuit properties. + +### quantum\_causal\_cone + + + +`quantum_causal_cone(qubit)` + +Returns causal cone of a qubit. + +A qubit’s causal cone is the set of qubits that can influence the output of that qubit through interactions, whether through multi-qubit gates or operations. Knowing the causal cone of a qubit can be useful when debugging faulty circuits, as it can help identify which wire(s) may be causing the problem. + +This method does not consider any classical data dependency in the `DAGCircuit`, classical bit wires are ignored for the purposes of building the causal cone. + +**Parameters** + +**qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The output qubit for which we want to find the causal cone. + +**Returns** + +The set of qubits whose interactions affect `qubit`. + +**Return type** + +Set\[[Qubit](qiskit.circuit.Qubit "qiskit.circuit.Qubit")] + +### quantum\_predecessors + + + +`quantum_predecessors(node)` + +Returns iterator of the predecessors of a node that are connected by a quantum edge as DAGOpNodes and DAGInNodes. + +### quantum\_successors + + + +`quantum_successors(node)` + +Returns iterator of the successors of a node that are connected by a quantum edge as Opnodes and DAGOutNodes. + +### remove\_all\_ops\_named + + + +`remove_all_ops_named(opname)` + +Remove all operation nodes with the given name. + +### remove\_ancestors\_of + + + +`remove_ancestors_of(node)` + +Remove all of the ancestor operation nodes of node. + +### remove\_clbits + + + +`remove_clbits(*clbits)` + +Remove classical bits from the circuit. All bits MUST be idle. Any registers with references to at least one of the specified bits will also be removed. + +**Parameters** + +**clbits** (*List\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – The bits to remove. + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – a clbit is not a [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit"), is not in the circuit, or is not idle. + +### remove\_cregs + + + +`remove_cregs(*cregs)` + +Remove classical registers from the circuit, leaving underlying bits in place. + +**Raises** + +* [**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – a creg is not a ClassicalRegister, or is not in +* **the circuit.** – + +### remove\_descendants\_of + + + +`remove_descendants_of(node)` + +Remove all of the descendant operation nodes of node. + +### remove\_nonancestors\_of + + + +`remove_nonancestors_of(node)` + +Remove all of the non-ancestors operation nodes of node. + +### remove\_nondescendants\_of + + + +`remove_nondescendants_of(node)` + +Remove all of the non-descendants operation nodes of node. + +### remove\_op\_node + + + +`remove_op_node(node)` + +Remove an operation node n. + +Add edges from predecessors to successors. + +### remove\_qregs + + + +`remove_qregs(*qregs)` + +Remove classical registers from the circuit, leaving underlying bits in place. + +**Raises** + +* [**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – a qreg is not a QuantumRegister, or is not in +* **the circuit.** – + +### remove\_qubits + + + +`remove_qubits(*qubits)` + +Remove quantum bits from the circuit. All bits MUST be idle. Any registers with references to at least one of the specified bits will also be removed. + +**Parameters** + +**qubits** (*List\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – The bits to remove. + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – a qubit is not a [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit"), is not in the circuit, or is not idle. + +### replace\_block\_with\_op + + + +`replace_block_with_op(node_block, op, wire_pos_map, cycle_check=True)` + +Replace a block of nodes with a single node. + +This is used to consolidate a block of DAGOpNodes into a single operation. A typical example is a block of gates being consolidated into a single `UnitaryGate` representing the unitary matrix of the block. + +**Parameters** + +* **node\_block** (*List\[*[*DAGNode*](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.DAGNode")*]*) – A list of dag nodes that represents the node block to be replaced +* **op** ([*qiskit.circuit.Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – The operation to replace the block with +* **wire\_pos\_map** (*Dict\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The dictionary mapping the bits to their positions in the output `qargs` or `cargs`. This is necessary to reconstruct the arg order over multiple gates in the combined single op node. If a [`Bit`](qiskit.circuit.Bit "qiskit.circuit.Bit") is not in the dictionary, it will not be added to the args; this can be useful when dealing with control-flow operations that have inherent bits in their `condition` or `target` fields. +* **cycle\_check** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set to True this method will check that replacing the provided `node_block` with a single node would introduce a cycle (which would invalidate the `DAGCircuit`) and will raise a `DAGCircuitError` if a cycle would be introduced. This checking comes with a run time penalty. If you can guarantee that your input `node_block` is a contiguous block and won’t introduce a cycle when it’s contracted to a single node, this can be set to `False` to improve the runtime performance of this method. + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if `cycle_check` is set to `True` and replacing the specified block introduces a cycle or if `node_block` is empty. + +**Returns** + +The op node that replaces the block. + +**Return type** + +[DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode") + +### reverse\_ops + + + +`reverse_ops()` + +Reverse the operations in the `self` circuit. + +**Returns** + +the reversed dag. + +**Return type** + +[DAGCircuit](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### separable\_circuits + + + +`separable_circuits(remove_idle_qubits=False)` + +Decompose the circuit into sets of qubits with no gates connecting them. + +**Parameters** + +**remove\_idle\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Flag denoting whether to remove idle qubits from the separated circuits. If `False`, each output circuit will contain the same number of qubits as `self`. + +**Returns** + +**The circuits resulting from separating `self` into sets** + +of disconnected qubits + +**Return type** + +List\[[DAGCircuit](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")] + +Each [`DAGCircuit`](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") instance returned by this method will contain the same number of clbits as `self`. The global phase information in `self` will not be maintained in the subcircuits returned by this method. + +### serial\_layers + + + +`serial_layers()` + +Yield a layer for all gates of this circuit. + +A serial layer is a circuit with one gate. The layers have the same structure as in layers(). + +### size + + + +`size(*, recurse=False)` + +Return the number of operations. If there is control flow present, this count may only be an estimate, as the complete control-flow path cannot be statically known. + +**Parameters** + +**recurse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True`, then recurse into control-flow operations. For loops with known-length iterators are counted unrolled. If-else blocks sum both of the two branches. While loops are counted as if the loop body runs once only. Defaults to `False` and raises [`DAGCircuitError`](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") if any control flow is present, to avoid silently returning a mostly meaningless number. + +**Returns** + +the circuit size + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if an unknown [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp") is present in a call with `recurse=True`, or any control flow is present in a non-recursive call. + +### substitute\_node + + + +`substitute_node(node, op, inplace=False, propagate_condition=True)` + +Replace an DAGOpNode with a single operation. qargs, cargs and conditions for the new operation will be inferred from the node to be replaced. The new operation will be checked to match the shape of the replaced operation. + +**Parameters** + +* **node** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")) – Node to be replaced +* **op** ([*qiskit.circuit.Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – The [`qiskit.circuit.Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") instance to be added to the DAG +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional, default False. If True, existing DAG node will be modified to include op. Otherwise, a new DAG node will be used. +* **propagate\_condition** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional, default True. If True, a condition on the `node` to be replaced will be applied to the new `op`. This is the legacy behaviour. If either node is a control-flow operation, this will be ignored. If the `op` already has a condition, [`DAGCircuitError`](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") is raised. + +**Returns** + +the new node containing the added operation. + +**Return type** + +[DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode") + +**Raises** + +* [**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – If replacement operation was incompatible with +* **location**\*\* of \*\***target node.** – + +### substitute\_node\_with\_dag + + + +`substitute_node_with_dag(node, input_dag, wires=None, propagate_condition=True)` + +Replace one node with dag. + +**Parameters** + +* **node** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")) – node to substitute +* **input\_dag** ([*DAGCircuit*](#qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – circuit that will substitute the node +* **wires** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*] | Dict\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*,* [*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – gives an order for (qu)bits in the input circuit. If a list, then the bits refer to those in the `input_dag`, and the order gets matched to the node wires by qargs first, then cargs, then conditions. If a dictionary, then a mapping of bits in the `input_dag` to those that the `node` acts on. +* **propagate\_condition** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` (default), then any `condition` attribute on the operation within `node` is propagated to each node in the `input_dag`. If `False`, then the `input_dag` is assumed to faithfully implement suitable conditional logic already. This is ignored for [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp")s (i.e. treated as if it is `False`); replacements of those must already fulfil the same conditional logic or this function would be close to useless for them. + +**Returns** + +maps node IDs from input\_dag to their new node incarnations in self. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if met with unexpected predecessor/successors + +### successors + + + +`successors(node)` + +Returns iterator of the successors of a node as DAGOpNodes and DAGOutNodes. + +### swap\_nodes + + + +`swap_nodes(node1, node2)` + +Swap connected nodes e.g. due to commutation. + +**Parameters** + +* **node1** (*OpNode*) – predecessor node +* **node2** (*OpNode*) – successor node + +**Raises** + +[**DAGCircuitError**](dagcircuit#qiskit.dagcircuit.DAGCircuitError "qiskit.dagcircuit.DAGCircuitError") – if either node is not an OpNode or nodes are not connected + +### topological\_nodes + + + +`topological_nodes(key=None)` + +Yield nodes in topological order. + +**Parameters** + +**key** (*Callable*) – A callable which will take a DAGNode object and return a string sort key. If not specified the `sort_key` attribute will be used as the sort key for each node. + +**Returns** + +node in topological order + +**Return type** + +generator([DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode"), [DAGInNode](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode"), or [DAGOutNode](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) + +### topological\_op\_nodes + + + +`topological_op_nodes(key=None)` + +Yield op nodes in topological order. + +Allowed to pass in specific key to break ties in top order + +**Parameters** + +**key** (*Callable*) – A callable which will take a DAGNode object and return a string sort key. If not specified the `sort_key` attribute will be used as the sort key for each node. + +**Returns** + +op node in topological order + +**Return type** + +generator([DAGOpNode](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")) + +### two\_qubit\_ops + + + +`two_qubit_ops()` + +Get list of 2 qubit operations. Ignore directives like snapshot and barrier. + +### width + + + +`width()` + +Return the total number of qubits + clbits used by the circuit. This function formerly returned the number of qubits by the calculation return len(self.\_wires) - self.num\_clbits() but was changed by issue #2564 to return number of qubits + clbits with the new function DAGCircuit.num\_qubits replacing the former semantic of DAGCircuit.width(). + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDepNode.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDepNode.md new file mode 100644 index 00000000000..de783da0179 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDepNode.md @@ -0,0 +1,117 @@ +--- +title: DAGDepNode +description: API reference for qiskit.dagcircuit.DAGDepNode +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGDepNode +--- + +# DAGDepNode + + + +`qiskit.dagcircuit.DAGDepNode(type=None, op=None, name=None, qargs=(), cargs=(), successors=None, predecessors=None, reachable=None, matchedwith=None, successorstovisit=None, isblocked=None, qindices=None, cindices=None, nid=-1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagdepnode.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Object to represent the information at a node in the DAGDependency(). + +It is used as the return value from \*\_nodes() functions and can be supplied to functions that take a node. + +## Attributes + + + +### type + + + +### name + + + +### cargs + + + +### sort\_key + + + +### node\_id + + + +### successors + + + +### predecessors + + + +### reachable + + + +### matchedwith + + + +### isblocked + + + +### successorstovisit + + + +### qindices + + + +### cindices + + + +### op + +Returns the Instruction object corresponding to the op for the node, else None + + + +### qargs + +Returns list of Qubit, else an empty list. + +## Methods + +### copy + + + +`copy()` + +Function to copy a DAGDepNode object. :returns: a copy of a DAGDepNode object. :rtype: DAGDepNode + +### semantic\_eq + + + +`static semantic_eq(node1, node2)` + +Check if DAG nodes are considered equivalent, e.g., as a node\_match for nx.is\_isomorphic. + +**Parameters** + +* **node1** ([*DAGDepNode*](#qiskit.dagcircuit.DAGDepNode "qiskit.dagcircuit.DAGDepNode")) – A node to compare. +* **node2** ([*DAGDepNode*](#qiskit.dagcircuit.DAGDepNode "qiskit.dagcircuit.DAGDepNode")) – The other node to compare. + +**Returns** + +If node1 == node2 + +**Return type** + +[Bool](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDependency.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDependency.md new file mode 100644 index 00000000000..dfa87146fa4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGDependency.md @@ -0,0 +1,390 @@ +--- +title: DAGDependency +description: API reference for qiskit.dagcircuit.DAGDependency +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGDependency +--- + +# DAGDependency + + + +`qiskit.dagcircuit.DAGDependency`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagdependency.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Object to represent a quantum circuit as a Directed Acyclic Graph (DAG) via operation dependencies (i.e. lack of commutation). + +The nodes in the graph are operations represented by quantum gates. The edges correspond to non-commutation between two operations (i.e. a dependency). A directed edge from node A to node B means that operation A does not commute with operation B. The object’s methods allow circuits to be constructed. + +The nodes in the graph have the following attributes: ‘operation’, ‘successors’, ‘predecessors’. + +**Example:** + +Bell circuit with no measurement. + +```python + ┌───┐ +qr_0: ┤ H ├──■── + └───┘┌─┴─┐ +qr_1: ─────┤ X ├ + └───┘ +``` + +The dependency DAG for the above circuit is represented by two nodes. The first one corresponds to Hadamard gate, the second one to the CNOT gate as the gates do not commute there is an edge between the two nodes. + +**Reference:** + +\[1] Iten, R., Moyard, R., Metger, T., Sutter, D. and Woerner, S., 2020. Exact and practical pattern matching for quantum circuit optimization. [arXiv:1909.05270](https://arxiv.org/abs/1909.05270) + +Create an empty DAGDependency. + +## Attributes + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}`. + + + +### global\_phase + +Return the global phase of the circuit. + +## Methods + +### add\_clbits + + + +`add_clbits(clbits)` + +Add individual clbit wires. + +### add\_creg + + + +`add_creg(creg)` + +Add clbits in a classical register. + +### add\_op\_node + + + +`add_op_node(operation, qargs, cargs)` + +Add a DAGDepNode to the graph and update the edges. + +**Parameters** + +* **operation** ([*qiskit.circuit.Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – operation as a quantum gate +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – list of qubits on which the operation acts +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Clbit*](qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – list of classical wires to attach to + +### add\_qreg + + + +`add_qreg(qreg)` + +Add qubits in a quantum register. + +### add\_qubits + + + +`add_qubits(qubits)` + +Add individual qubit wires. + +### copy + + + +`copy()` + +Function to copy a DAGDependency object. :returns: a copy of a DAGDependency object. :rtype: DAGDependency + +### depth + + + +`depth()` + +Return the circuit depth. :returns: the circuit depth :rtype: int + +### direct\_predecessors + + + +`direct_predecessors(node_id)` + +Direct predecessors id of a given node as sorted list. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +direct predecessors id as a sorted list + +**Return type** + +List + +### direct\_successors + + + +`direct_successors(node_id)` + +Direct successors id of a given node as sorted list. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +direct successors id as a sorted list + +**Return type** + +List + +### draw + + + +`draw(scale=0.7, filename=None, style='color')` + +Draws the DAGDependency graph. + +This function needs pydot \<[https://github.com/erocarrera/pydot](https://github.com/erocarrera/pydot)>, which in turn needs Graphviz \<[https://www.graphviz.org/](https://www.graphviz.org/)>\` to be installed. + +**Parameters** + +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – scaling factor +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to (format inferred from name) +* **style** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – ‘plain’: B\&W graph ‘color’ (default): color input/output/op nodes + +**Returns** + +if in Jupyter notebook and not saving to file, otherwise None. + +**Return type** + +Ipython.display.Image + +### get\_all\_edges + + + +`get_all_edges()` + +Enumeration of all edges. + +**Returns** + +corresponding to the label. + +**Return type** + +List + +### get\_edges + + + +`get_edges(src_id, dest_id)` + +Edge enumeration between two nodes through method get\_all\_edge\_data. + +**Parameters** + +* **src\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of the first node. +* **dest\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of the second node. + +**Returns** + +corresponding to all edges between the two nodes. + +**Return type** + +List + +### get\_in\_edges + + + +`get_in_edges(node_id)` + +Enumeration of all incoming edges for a given node. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +corresponding incoming edges data. + +**Return type** + +List + +### get\_node + + + +`get_node(node_id)` + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +corresponding to the label. + +**Return type** + +node + +### get\_nodes + + + +`get_nodes()` + +**Returns** + +iterator over all the nodes. + +**Return type** + +generator([dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) + +### get\_out\_edges + + + +`get_out_edges(node_id)` + +Enumeration of all outgoing edges for a given node. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +corresponding outgoing edges data. + +**Return type** + +List + +### predecessors + + + +`predecessors(node_id)` + +Predecessors id of a given node as sorted list. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +all predecessors id as a sorted list + +**Return type** + +List + +### replace\_block\_with\_op + + + +`replace_block_with_op(node_block, op, wire_pos_map, cycle_check=True)` + +Replace a block of nodes with a single node. + +This is used to consolidate a block of DAGDepNodes into a single operation. A typical example is a block of CX and SWAP gates consolidated into a LinearFunction. This function is an adaptation of a similar function from DAGCircuit. + +It is important that such consolidation preserves commutativity assumptions present in DAGDependency. As an example, suppose that every node in a block \[A, B, C, D] commutes with another node E. Let F be the consolidated node, F = A o B o C o D. Then F also commutes with E, and thus the result of replacing \[A, B, C, D] by F results in a valid DAGDependency. That is, any deduction about commutativity in consolidated DAGDependency is correct. On the other hand, suppose that at least one of the nodes, say B, does not commute with E. Then the consolidated DAGDependency would imply that F does not commute with E. Even though F and E may actually commute, it is still safe to assume that they do not. That is, the current implementation of consolidation may lead to suboptimal but not to incorrect results. + +**Parameters** + +* **node\_block** (*List\[*[*DAGDepNode*](qiskit.dagcircuit.DAGDepNode "qiskit.dagcircuit.DAGDepNode")*]*) – A list of dag nodes that represents the node block to be replaced +* **op** ([*qiskit.circuit.Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – The operation to replace the block with +* **wire\_pos\_map** (*Dict\[*[*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The dictionary mapping the qarg to the position. This is necessary to reconstruct the qarg order over multiple gates in the combined single op node. +* **cycle\_check** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set to True this method will check that replacing the provided `node_block` with a single node would introduce a cycle (which would invalidate the `DAGDependency`) and will raise a `DAGDependencyError` if a cycle would be introduced. This checking comes with a run time penalty. If you can guarantee that your input `node_block` is a contiguous block and won’t introduce a cycle when it’s contracted to a single node, this can be set to `False` to improve the runtime performance of this method. + +**Raises** + +[**DAGDependencyError**](dagcircuit#qiskit.dagcircuit.DAGDependencyError "qiskit.dagcircuit.DAGDependencyError") – if `cycle_check` is set to `True` and replacing the specified block introduces a cycle or if `node_block` is empty. + +### size + + + +`size()` + +Returns the number of gates in the circuit + +### successors + + + +`successors(node_id)` + +Successors id of a given node as sorted list. + +**Parameters** + +**node\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – label of considered node. + +**Returns** + +all successors id as a sorted list + +**Return type** + +List + +### to\_retworkx + + + +`to_retworkx()` + +Returns the DAGDependency in retworkx format. + +### topological\_nodes + + + +`topological_nodes()` + +Yield nodes in topological order. + +**Returns** + +node in topological order. + +**Return type** + +generator([DAGNode](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.DAGNode")) + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGInNode.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGInNode.md new file mode 100644 index 00000000000..b8d32d60992 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGInNode.md @@ -0,0 +1,55 @@ +--- +title: DAGInNode +description: API reference for qiskit.dagcircuit.DAGInNode +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGInNode +--- + +# DAGInNode + + + +`qiskit.dagcircuit.DAGInNode(wire)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagnode.py "view source code") + +Bases: [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.dagnode.DAGNode") + +Object to represent an incoming wire node in the DAGCircuit. + +Create an incoming node + +## Attributes + + + +### wire + + + +### sort\_key + +## Methods + +### semantic\_eq + + + +`static semantic_eq(node1, node2, bit_indices1, bit_indices2)` + +Check if DAG nodes are considered equivalent, e.g., as a node\_match for [`rustworkx.is_isomorphic_node_match()`](https://www.rustworkx.org/apiref/rustworkx.is_isomorphic_node_match.html#rustworkx.is_isomorphic_node_match "(in rustworkx v0.14.0)"). + +**Parameters** + +* **node1** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](#qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – A node to compare. +* **node2** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](#qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – The other node to compare. +* **bit\_indices1** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node1 +* **bit\_indices2** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node2 + +**Returns** + +If node1 == node2 + +**Return type** + +[Bool](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGNode.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGNode.md new file mode 100644 index 00000000000..5f8679d3a11 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGNode.md @@ -0,0 +1,45 @@ +--- +title: DAGNode +description: API reference for qiskit.dagcircuit.DAGNode +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGNode +--- + +# DAGNode + + + +`qiskit.dagcircuit.DAGNode(nid=-1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagnode.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Parent class for DAGOpNode, DAGInNode, and DAGOutNode. + +Create a node + +## Methods + +### semantic\_eq + + + +`static semantic_eq(node1, node2, bit_indices1, bit_indices2)` + +Check if DAG nodes are considered equivalent, e.g., as a node\_match for [`rustworkx.is_isomorphic_node_match()`](https://www.rustworkx.org/apiref/rustworkx.is_isomorphic_node_match.html#rustworkx.is_isomorphic_node_match "(in rustworkx v0.14.0)"). + +**Parameters** + +* **node1** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – A node to compare. +* **node2** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – The other node to compare. +* **bit\_indices1** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node1 +* **bit\_indices2** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node2 + +**Returns** + +If node1 == node2 + +**Return type** + +[Bool](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOpNode.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOpNode.md new file mode 100644 index 00000000000..bcef359289d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOpNode.md @@ -0,0 +1,69 @@ +--- +title: DAGOpNode +description: API reference for qiskit.dagcircuit.DAGOpNode +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGOpNode +--- + +# DAGOpNode + + + +`qiskit.dagcircuit.DAGOpNode(op, qargs=(), cargs=(), dag=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagnode.py "view source code") + +Bases: [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.dagnode.DAGNode") + +Object to represent an Instruction at a node in the DAGCircuit. + +Create an Instruction node + +## Attributes + + + +### op + + + +### qargs + + + +### cargs + + + +### sort\_key + + + +### name + +Returns the Instruction name corresponding to the op for this node + +## Methods + +### semantic\_eq + + + +`static semantic_eq(node1, node2, bit_indices1, bit_indices2)` + +Check if DAG nodes are considered equivalent, e.g., as a node\_match for [`rustworkx.is_isomorphic_node_match()`](https://www.rustworkx.org/apiref/rustworkx.is_isomorphic_node_match.html#rustworkx.is_isomorphic_node_match "(in rustworkx v0.14.0)"). + +**Parameters** + +* **node1** ([*DAGOpNode*](#qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – A node to compare. +* **node2** ([*DAGOpNode*](#qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – The other node to compare. +* **bit\_indices1** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node1 +* **bit\_indices2** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node2 + +**Returns** + +If node1 == node2 + +**Return type** + +[Bool](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") + diff --git a/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOutNode.md b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOutNode.md new file mode 100644 index 00000000000..e74b7d0f66a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.dagcircuit.DAGOutNode.md @@ -0,0 +1,55 @@ +--- +title: DAGOutNode +description: API reference for qiskit.dagcircuit.DAGOutNode +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.dagcircuit.DAGOutNode +--- + +# DAGOutNode + + + +`qiskit.dagcircuit.DAGOutNode(wire)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/dagcircuit/dagnode.py "view source code") + +Bases: [`DAGNode`](qiskit.dagcircuit.DAGNode "qiskit.dagcircuit.dagnode.DAGNode") + +Object to represent an outgoing wire node in the DAGCircuit. + +Create an outgoing node + +## Attributes + + + +### wire + + + +### sort\_key + +## Methods + +### semantic\_eq + + + +`static semantic_eq(node1, node2, bit_indices1, bit_indices2)` + +Check if DAG nodes are considered equivalent, e.g., as a node\_match for [`rustworkx.is_isomorphic_node_match()`](https://www.rustworkx.org/apiref/rustworkx.is_isomorphic_node_match.html#rustworkx.is_isomorphic_node_match "(in rustworkx v0.14.0)"). + +**Parameters** + +* **node1** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](#qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – A node to compare. +* **node2** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")*,* [*DAGInNode*](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")*,* [*DAGOutNode*](#qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")) – The other node to compare. +* **bit\_indices1** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node1 +* **bit\_indices2** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Dictionary mapping Bit instances to their index within the circuit containing node2 + +**Returns** + +If node1 == node2 + +**Return type** + +[Bool](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") + diff --git a/docs/api/qiskit/0.46/qiskit.extensions.SingleQubitUnitary.md b/docs/api/qiskit/0.46/qiskit.extensions.SingleQubitUnitary.md new file mode 100644 index 00000000000..618f334a443 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.extensions.SingleQubitUnitary.md @@ -0,0 +1,424 @@ +--- +title: SingleQubitUnitary +description: API reference for qiskit.extensions.SingleQubitUnitary +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.extensions.SingleQubitUnitary +--- + +# SingleQubitUnitary + + + +`qiskit.extensions.SingleQubitUnitary(unitary_matrix, mode='ZYZ', up_to_diagonal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/extensions/quantum_initializer/squ.py "view source code") + +Bases: [`Gate`](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +Single-qubit unitary. + +**Parameters** + +* **unitary\_matrix** – $2 imes 2$ unitary (given as a (complex) `numpy.ndarray`). +* **mode** – determines the used decomposition by providing the rotation axes. +* **up\_to\_diagonal** – the single-qubit unitary is decomposed up to a diagonal matrix, i.e. a unitary $U'$ is implemented such that there exists a diagonal matrix $D$ with $U = D U'$. + +Create a new single qubit gate based on the unitary `u`. + + + The class `qiskit.extensions.quantum_initializer.squ.SingleQubitUnitary` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. Instead, you can use qiskit.circuit.library.UnitaryGate. + + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.extensions.SingleQubitUnitary.base_class "qiskit.extensions.SingleQubitUnitary.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### diag + +Returns the diagonal gate D up to which the single-qubit unitary u is implemented. + +I.e. u=D.u’, where u’ is the unitary implemented by the found circuit. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation and handling of the arguments and its relationship. + +For example, `cx([q[0],q[1]], q[2])` means `cx(q[0], q[2]); cx(q[1], q[2])`. This method yields the arguments in the right grouping. In the given example: + +```python +in: [[q[0],q[1]], q[2]],[] +outs: [q[0], q[2]], [] + [q[1], q[2]], [] +``` + +The general broadcasting rules are: + +> * If len(qargs) == 1: +> +> ```python +> [q[0], q[1]] -> [q[0]],[q[1]] +> ``` +> +> * If len(qargs) == 2: +> +> ```python +> [[q[0], q[1]], [r[0], r[1]]] -> [q[0], r[0]], [q[1], r[1]] +> [[q[0]], [r[0], r[1]]] -> [q[0], r[0]], [q[0], r[1]] +> [[q[0], q[1]], [r[0]]] -> [q[0], r[0]], [q[1], r[0]] +> ``` +> +> * If len(qargs) >= 3: +> +> ```python +> [q[0], q[1]], [r[0], r[1]], ...] -> [q[0], r[0], ...], [q[1], r[1], ...] +> ``` + +**Parameters** + +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of quantum bit arguments. +* **cargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of classical bit arguments. + +**Returns** + +A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +**Return type** + +[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")]] + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### control + + + +`control(num_ctrl_qubits=1, label=None, ctrl_state=None)` + +Return controlled version of gate. See [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") for usage. + +**Parameters** + +* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of controls to add to gate (default: `1`) +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – optional gate label +* **ctrl\_state** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The control state in decimal or as a bitstring (e.g. `'111'`). If `None`, use `2**num_ctrl_qubits-1`. + +**Returns** + +Controlled version of gate. This default algorithm uses `num_ctrl_qubits-1` ancilla qubits so returns a gate of size `num_qubits + 2*num_ctrl_qubits - 1`. + +**Return type** + +[qiskit.circuit.ControlledGate](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – unrecognized mode or invalid ctrl\_state + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Return the inverse. + +Note that the resulting gate has an empty `params` property. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### power + + + +`power(exponent)` + +Creates a unitary gate as gate^exponent. + +**Parameters** + +**exponent** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Gate^exponent + +**Returns** + +To which to\_matrix is self.to\_matrix^exponent. + +**Return type** + +.library.UnitaryGate + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If Gate is not unitary + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_matrix + + + +`to_matrix()` + +Return a Numpy.array for the gate unitary matrix. + +**Returns** + +if the Gate subclass has a matrix definition. + +**Return type** + +np.ndarray + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If a Gate subclass does not implement this method an exception will be raised when this base class method is called. + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Single-qubit unitary gate parameter has to be an ndarray. + diff --git a/docs/api/qiskit/0.46/qiskit.extensions.Snapshot.md b/docs/api/qiskit/0.46/qiskit.extensions.Snapshot.md new file mode 100644 index 00000000000..6aa4e04a085 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.extensions.Snapshot.md @@ -0,0 +1,322 @@ +--- +title: Snapshot +description: API reference for qiskit.extensions.Snapshot +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.extensions.Snapshot +--- + +# Snapshot + + + +`qiskit.extensions.Snapshot(label, snapshot_type='statevector', num_qubits=0, num_clbits=0, params=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/extensions/simulator/snapshot.py "view source code") + +Bases: [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +Simulator snapshot instruction. + +Create new snapshot instruction. + + + The class `qiskit.extensions.simulator.snapshot.Snapshot` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. The Snapshot instruction has been superseded by Qiskit Aer’s save instructions, see [https://qiskit.org/ecosystem/aer/apidocs/aer\_library.html#saving-simulator-data](https://qiskit.org/ecosystem/aer/apidocs/aer_library.html#saving-simulator-data). + + +**Parameters** + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the snapshot label for result data. +* **snapshot\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the type of the snapshot. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits for the snapshot type \[Default: 0]. +* **num\_clbits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of classical bits for the snapshot type \[Default: 0]. +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – the parameters for snapshot\_type \[Default: None]. + +**Raises** + +[**ExtensionError**](extensions#qiskit.extensions.ExtensionError "qiskit.extensions.ExtensionError") – if snapshot label is invalid. + +## Attributes + + + +### base\_class + +Get the base class of this instruction. This is guaranteed to be in the inheritance tree of `self`. + +The “base class” of an instruction is the lowest class in its inheritance tree that the object should be considered entirely compatible with for \_all\_ circuit applications. This typically means that the subclass is defined purely to offer some sort of programmer convenience over the base class, and the base class is the “true” class for a behavioural perspective. In particular, you should *not* override [`base_class`](#qiskit.extensions.Snapshot.base_class "qiskit.extensions.Snapshot.base_class") if you are defining a custom version of an instruction that will be implemented differently by hardware, such as an alternative measurement strategy, or a version of a parametrised gate with a particular set of parameters for the purposes of distinguishing it in a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") from the full parametrised gate. + +This is often exactly equivalent to `type(obj)`, except in the case of singleton instances of standard-library instructions. These singleton instances are special subclasses of their base class, and this property will return that base. For example: + +```python +>>> isinstance(XGate(), XGate) +True +>>> type(XGate()) is XGate +False +>>> XGate().base_class is XGate +True +``` + +In general, you should not rely on the precise class of an instruction; within a given circuit, it is expected that `Instruction.name` should be a more suitable discriminator in most situations. + + + +### condition + +The classical condition on the instruction. + + + +### condition\_bits + +Get Clbits in condition. + + + +### decompositions + +Get the decompositions of the instruction from the SessionEquivalenceLibrary. + + + +### definition + +Return definition in terms of other basic gates. + + + +### duration + +Get the duration. + + + +### label + +Return instruction label + + + +### mutable + +Is this instance is a mutable unique instance or not. + +If this attribute is `False` the gate instance is a shared singleton and is not mutable. + + + +### name + +Return the name. + + + +### num\_clbits + +Return the number of clbits. + + + +### num\_qubits + +Return the number of qubits. + + + +### params + +return instruction params. + + + +### snapshot\_type + +Return snapshot type + + + +### unit + +Get the time unit of duration. + +## Methods + +### add\_decomposition + + + +`add_decomposition(decomposition)` + +Add a decomposition of the instruction to the SessionEquivalenceLibrary. + +### assemble + + + +`assemble()` + +Assemble a QasmQobjInstruction + +### broadcast\_arguments + + + +`broadcast_arguments(qargs, cargs)` + +Validation of the arguments. + +**Parameters** + +* **qargs** (*List*) – List of quantum bit arguments. +* **cargs** (*List*) – List of classical bit arguments. + +**Yields** + +*Tuple(List, List)* – A tuple with single arguments. + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the input is not valid. For example, the number of arguments does not match the gate expectation. + +### c\_if + + + +`c_if(classical, val)` + +Set a classical equality condition on this instruction between the register or cbit `classical` and value `val`. + + + This is a setter method, not an additive one. Calling this multiple times will silently override any previously set condition; it does not stack. + + +### copy + + + +`copy(name=None)` + +Copy of the instruction. + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name to be given to the copied circuit, if `None` then the name stays the same. + +**Returns** + +a copy of the current instruction, with the name updated if it was provided + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### inverse + + + +`inverse()` + +Special case. Return self. + +### is\_parameterized + + + +`is_parameterized()` + +Return True .IFF. instruction is parameterized else False + +### qasm + + + +`qasm()` + +Return a default OpenQASM string for the instruction. + +Derived instructions may override this to print in a different format (e.g. `measure q[0] -> c[0];`). + + + The method `qiskit.circuit.instruction.Instruction.qasm()` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong. + + +### repeat + + + +`repeat(n)` + +Creates an instruction with gate repeated n amount of times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of times to repeat the instruction + +**Returns** + +Containing the definition. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If n \< 1. + +### reverse\_ops + + + +`reverse_ops()` + +For a composite instruction, reverse the order of sub-instructions. + +This is done by recursively reversing all sub-instructions. It does not invert any gate. + +**Returns** + +**a new instruction with** + +sub-instructions reversed. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### soft\_compare + + + +`soft_compare(other)` + +Soft comparison between gates. Their names, number of qubits, and classical bit numbers must match. The number of parameters must match. Each parameter is compared. If one is a ParameterExpression then it is not taken into account. + +**Parameters** + +**other** (*instruction*) – other instruction. + +**Returns** + +are self and other equal up to parameter expressions. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### to\_mutable + + + +`to_mutable()` + +Return a mutable copy of this gate. + +This method will return a new mutable copy of this gate instance. If a singleton instance is being used this will be a new unique instance that can be mutated. If the instance is already mutable it will be a deepcopy of that instance. + +### validate\_parameter + + + +`validate_parameter(parameter)` + +Instruction parameters has no validation or normalization. + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.OperatorBase.md b/docs/api/qiskit/0.46/qiskit.opflow.OperatorBase.md new file mode 100644 index 00000000000..9cb5f188870 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.OperatorBase.md @@ -0,0 +1,420 @@ +--- +title: OperatorBase +description: API reference for qiskit.opflow.OperatorBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.OperatorBase +--- + +# OperatorBase + + + +`qiskit.opflow.OperatorBase`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/operator_base.py "view source code") + +Bases: `StarAlgebraMixin`, `TensorMixin`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: A base class for all Operators: PrimitiveOps, StateFns, ListOps, etc. Operators are defined as functions which take one complex binary function to another. These complex binary functions are represented by StateFns, which are themselves a special class of Operators taking only the `Zero` StateFn to the complex binary function they represent. + +Operators can be used to construct complicated functions and computation, and serve as the building blocks for algorithms. + + + The class `qiskit.opflow.operator_base.OperatorBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + +The number of qubits over which the Operator is defined. If `op.num_qubits == 5`, then `op.eval('1' * 5)` will be valid, but `op.eval('11')` will not. + +**Returns** + +The number of qubits accepted by the Operator’s underlying function. + + + +### parameters + +Return a set of Parameter objects contained in the Operator. + + + +### settings + +Return settings of this object in a dictionary. + +You can, for example, use this `settings` dictionary to serialize the object in JSON format, if the JSON encoder you use supports all types in the dictionary. + +**Returns** + +Object settings in a dictionary. + +## Methods + +### add + + + +`abstract add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`abstract adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### assign\_parameters + + + +`abstract assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]]*) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### bind\_parameters + + + +`bind_parameters(param_dict)` + +Same as assign\_parameters, but maintained for consistency with QuantumCircuit in Terra (which has both assign\_parameters and bind\_parameters). + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### compose + + + +`abstract compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### copy + + + +`copy()` + +Return a deep copy of the Operator. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`abstract equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`abstract eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### is\_hermitian + + + +`is_hermitian()` + +Return True if the operator is hermitian. + +Returns: Boolean value + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### mul + + + +`abstract mul(scalar)` + +Returns the scalar multiplication of the Operator, overloaded by `*`, including support for Terra’s `Parameters`, which can be bound to values later (via `bind_parameters`). + +**Parameters** + +**scalar** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The real or complex scalar by which to multiply the Operator, or the `ParameterExpression` to serve as a placeholder for a scalar factor. + +**Returns** + +An `OperatorBase` equivalent to product of self and scalar. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### neg + + + +`neg()` + +Return the Operator’s negation, effectively just multiplying by -1.0, overloaded by `-`. + +**Returns** + +An `OperatorBase` equivalent to the negation of self. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`abstract permute(permutation)` + +Permutes the qubits of the operator. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j should be permuted to position permutation\[j]. + +**Returns** + +A new OperatorBase containing the permuted operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### primitive\_strings + + + +`abstract primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`abstract reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +### tensor + + + +`abstract tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensorpower + + + +`abstract tensorpower(other)` + +Return tensor product with self multiple times, overloaded by `^`. + +**Parameters** + +**other** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The int number of times to tensor product self with itself via `tensorpower`. + +**Returns** + +An `OperatorBase` equivalent to the tensorpower of self by other. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### to\_circuit\_op + + + +`abstract to_circuit_op()` + +Returns a `CircuitOp` equivalent to this Operator. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_matrix + + + +`abstract to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`abstract to_matrix_op(massive=False)` + +Returns a `MatrixOp` equivalent to this Operator. + +**Return type** + +[*OperatorBase*](#qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_spmatrix + + + +`to_spmatrix()` + +Return SciPy sparse matrix representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. + +**Returns** + +The SciPy `spmatrix` equivalent to this Operator. + +**Return type** + +*spmatrix* + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.AbelianGrouper.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.AbelianGrouper.md new file mode 100644 index 00000000000..2061204b164 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.AbelianGrouper.md @@ -0,0 +1,74 @@ +--- +title: AbelianGrouper +description: API reference for qiskit.opflow.converters.AbelianGrouper +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.converters.AbelianGrouper +--- + +# AbelianGrouper + + + +`qiskit.opflow.converters.AbelianGrouper(traverse=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/converters/abelian_grouper.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: The AbelianGrouper converts SummedOps into a sum of Abelian sums. + +Meaning, it will traverse the Operator, and when it finds a SummedOp, it will evaluate which of the summed sub-Operators commute with one another. It will then convert each of the groups of commuting Operators into their own SummedOps, and return the sum-of-commuting-SummedOps. This is particularly useful for cases where mutually commuting groups can be handled similarly, as in the case of Pauli Expectations, where commuting Paulis have the same diagonalizing circuit rotation, or Pauli Evolutions, where commuting Paulis can be diagonalized together. + + + The class `qiskit.opflow.converters.abelian_grouper.AbelianGrouper` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**traverse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to convert only the Operator passed to `convert`, or traverse down that Operator. + +## Methods + +### convert + + + +`convert(operator)` + +Check if operator is a SummedOp, in which case covert it into a sum of mutually commuting sums, or if the Operator contains sub-Operators and `traverse` is True, attempt to convert any sub-Operators. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to attempt to convert. + +**Returns** + +The converted Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### group\_subops + + + +`classmethod group_subops(list_op)` + +Given a ListOp, attempt to group into Abelian ListOps of the same type. + +**Parameters** + +**list\_op** ([*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp")) – The Operator to group into Abelian groups + +**Returns** + +The grouped Operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – If any of list\_op’s sub-ops is not `PauliOp`. + +**Return type** + +[*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.CircuitSampler.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.CircuitSampler.md new file mode 100644 index 00000000000..0c2cdb7cccd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.CircuitSampler.md @@ -0,0 +1,108 @@ +--- +title: CircuitSampler +description: API reference for qiskit.opflow.converters.CircuitSampler +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.converters.CircuitSampler +--- + +# CircuitSampler + + + +`qiskit.opflow.converters.CircuitSampler(backend, statevector=None, param_qobj=False, attach_results=False, caching='last')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/converters/circuit_sampler.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: The CircuitSampler traverses an Operator and converts any CircuitStateFns into approximations of the state function by a DictStateFn or VectorStateFn using a quantum backend. Note that in order to approximate the value of the CircuitStateFn, it must 1) send state function through a depolarizing channel, which will destroy all phase information and 2) replace the sampled frequencies with **square roots** of the frequency, rather than the raw probability of sampling (which would be the equivalent of sampling the **square** of the state function, per the Born rule. + +The CircuitSampler aggressively caches transpiled circuits to handle re-parameterization of the same circuit efficiently. If you are converting multiple different Operators, you are better off using a different CircuitSampler for each Operator to avoid cache thrashing. + + + The class `qiskit.opflow.converters.circuit_sampler.CircuitSampler` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *|*[*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.quantum_instance.QuantumInstance")) – The quantum backend or QuantumInstance to use to sample the circuits. +* **statevector** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If backend is a statevector backend, whether to replace the CircuitStateFns with DictStateFns (from the counts) or VectorStateFns (from the statevector). `None` will set this argument automatically based on the backend. +* **attach\_results** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to attach the data from the backend `Results` object for a given `` CircuitStateFn` `` to an `execution_results` field added the converted `DictStateFn` or `VectorStateFn`. +* **param\_qobj** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to use Aer’s parameterized Qobj capability to avoid re-assembling the circuits. +* **caching** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The caching strategy. Can be ‘last’ (default) to store the last operator that was converted, set to ‘all’ to cache all processed operators. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Set statevector or param\_qobj True when not supported by backend. + +## Attributes + + + +### quantum\_instance + +Returns the quantum instance. + +**Returns** + +The QuantumInstance used by the CircuitSampler + +## Methods + +### clear\_cache + + + +`clear_cache()` + +Clear the cache of sampled operator expressions. + +### convert + + + +`convert(operator, params=None)` + +Converts the Operator to one in which the CircuitStateFns are replaced by DictStateFns or VectorStateFns. Extracts the CircuitStateFns out of the Operator, caches them, calls `sample_circuits` below to get their converted replacements, and replaces the CircuitStateFns in operator with the replacement StateFns. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to convert +* **params** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]] | None*) – A dictionary mapping parameters to either single binding values or lists of binding values. + +**Returns** + +The converted Operator with CircuitStateFns replaced by DictStateFns or VectorStateFns. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if extracted circuits are empty. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### sample\_circuits + + + +`sample_circuits(circuit_sfns=None, param_bindings=None)` + +Samples the CircuitStateFns and returns a dict associating their `id()` values to their replacement DictStateFn or VectorStateFn. If param\_bindings is provided, the CircuitStateFns are broken into their parameterizations, and a list of StateFns is returned in the dict for each circuit `id()`. Note that param\_bindings is provided here in a different format than in `convert`, and lists of parameters within the dict is not supported, and only binding dicts which are valid to be passed into Terra can be included in this list. + +**Parameters** + +* **circuit\_sfns** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*CircuitStateFn*](qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn")*] | None*) – The list of CircuitStateFns to sample. +* **param\_bindings** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – The parameterizations to bind to each CircuitStateFn. + +**Returns** + +The dictionary mapping ids of the CircuitStateFns to their replacement StateFns. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if extracted circuits are empty. + +**Return type** + +[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"), [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*StateFn*](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn")]] + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.ConverterBase.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.ConverterBase.md new file mode 100644 index 00000000000..018e0dd800f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.ConverterBase.md @@ -0,0 +1,44 @@ +--- +title: ConverterBase +description: API reference for qiskit.opflow.converters.ConverterBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.converters.ConverterBase +--- + +# ConverterBase + + + +`qiskit.opflow.converters.ConverterBase`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/converters/converter_base.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: Converters take an Operator and return a new Operator, generally isomorphic in some way with the first, but with certain desired properties. For example, a converter may accept `CircuitOp` and return a `SummedOp` of `PauliOps` representing the circuit unitary. Converters may not have polynomial space or time scaling in their operations. On the contrary, many converters, such as a `MatrixExpectation` or `MatrixEvolution`, which convert `PauliOps` to `MatrixOps` internally, will require time or space exponential in the number of qubits unless a clever trick is known (such as the use of sparse matrices). + + + The class `qiskit.opflow.converters.converter_base.ConverterBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### convert + + + +`abstract convert(operator)` + +Accept the Operator and return the converted Operator + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to convert. + +**Returns** + +The converted Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.DictToCircuitSum.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.DictToCircuitSum.md new file mode 100644 index 00000000000..2ee3d728f50 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.DictToCircuitSum.md @@ -0,0 +1,50 @@ +--- +title: DictToCircuitSum +description: API reference for qiskit.opflow.converters.DictToCircuitSum +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.converters.DictToCircuitSum +--- + +# DictToCircuitSum + + + +`qiskit.opflow.converters.DictToCircuitSum(traverse=True, convert_dicts=True, convert_vectors=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/converters/dict_to_circuit_sum.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: Converts `DictStateFns` or `VectorStateFns` to equivalent `CircuitStateFns` or sums thereof. The behavior of this class can be mostly replicated by calling `to_circuit_op` on an Operator, but with the added control of choosing whether to convert only `DictStateFns` or `VectorStateFns`, rather than both. + + + The class `qiskit.opflow.converters.dict_to_circuit_sum.DictToCircuitSum` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **traverse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to recurse down into Operators with internal sub-operators for conversion. +* **convert\_dicts** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to convert VectorStateFn. +* **convert\_vectors** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to convert DictStateFns. + +## Methods + +### convert + + + +`convert(operator)` + +Convert the Operator to `CircuitStateFns`, recursively if `traverse` is True. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to convert + +**Returns** + +The converted Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.PauliBasisChange.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.PauliBasisChange.md new file mode 100644 index 00000000000..be2c8656853 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.PauliBasisChange.md @@ -0,0 +1,268 @@ +--- +title: PauliBasisChange +description: API reference for qiskit.opflow.converters.PauliBasisChange +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.converters.PauliBasisChange +--- + +# PauliBasisChange + + + +`qiskit.opflow.converters.PauliBasisChange(destination_basis=None, traverse=True, replacement_fn=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/converters/pauli_basis_change.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: Converter for changing Paulis into other bases. By default, the diagonal basis composed only of Pauli \{Z, I}^n is used as the destination basis to which to convert. Meaning, if a Pauli containing X or Y terms is passed in, which cannot be sampled or evolved natively on some Quantum hardware, the Pauli can be replaced by a composition of a change of basis circuit and a Pauli composed of only Z and I terms (diagonal), which can be evolved or sampled natively on the Quantum hardware. + +The replacement function determines how the `PauliOps` should be replaced by their computed change-of-basis `CircuitOps` and destination `PauliOps`. Several convenient out-of-the-box replacement functions have been added as static methods, such as `measurement_replacement_fn`. + +This class uses the typical basis change method found in most Quantum Computing textbooks (such as on page 210 of Nielsen and Chuang’s, “Quantum Computation and Quantum Information”, ISBN: 978-1-107-00217-3), which involves diagonalizing the single-qubit Paulis with H and S† gates, mapping the eigenvectors of the diagonalized origin Pauli to the diagonalized destination Pauli using CNOTS, and then de-diagonalizing any single qubit Paulis to their non-diagonal destination values. Many other methods are possible, as well as variations on this method, such as the placement of the CNOT chains. + + + The class `qiskit.opflow.converters.pauli_basis_change.PauliBasisChange` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **destination\_basis** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") *| None*) – The Pauli into the basis of which the operators will be converted. If None is specified, the destination basis will be the diagonal (\{I, Z}^n) basis requiring only single qubit rotations. + +* **traverse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If true and the operator passed into convert contains sub-Operators, such as ListOp, traverse the Operator and apply the conversion to every applicable sub-operator within it. + +* **replacement\_fn** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – + + A function specifying what to do with the basis-change `CircuitOp` and destination `PauliOp` when converting an Operator and replacing converted values. By default, this will be + + > 1. For StateFns (or Measurements): replacing the StateFn with ComposedOp(StateFn(d), c) where c is the conversion circuit and d is the destination Pauli, so the overall beginning and ending operators are equivalent. + > 2. For non-StateFn Operators: replacing the origin p with c·d·c†, where c is the conversion circuit and d is the destination, so the overall beginning and ending operators are equivalent. + +## Attributes + + + +### destination + +The destination `PauliOp`, or `None` if using the default destination, the diagonal basis. + +## Methods + +### construct\_cnot\_chain + + + +`construct_cnot_chain(diag_pauli_op1, diag_pauli_op2)` + +Construct a `CircuitOp` (or `PauliOp` if equal to the identity) which takes the eigenvectors of `diag_pauli_op1` to the eigenvectors of `diag_pauli_op2`, assuming both are diagonal (or performing this operation on their diagonalized Paulis implicitly if not). This works by the insight that the eigenvalue of a diagonal Pauli’s eigenvector is equal to or -1 if the parity is 1 and 1 if the parity is 0, or 1 - (2 \* parity). Therefore, using CNOTs, we can write the parity of diag\_pauli\_op1’s significant bits onto some qubit, and then write out that parity onto diag\_pauli\_op2’s significant bits. + +**Parameters** + +* **diag\_pauli\_op1** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – The origin `PauliOp`. +* **diag\_pauli\_op2** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – The destination `PauliOp`. + +**Returns** + +The `PrimitiveOp` performs the mapping. + +**Return type** + +[*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +### convert + + + +`convert(operator)` + +Given a `PauliOp`, or an Operator containing `PauliOps` if `_traverse` is True, converts each Pauli into the basis specified by self.\_destination and a basis-change-circuit, calls `replacement_fn` with these two Operators, and replaces the `PauliOps` with the output of `replacement_fn`. For example, for the built-in `operator_replacement_fn` below, each PauliOp p will be replaced by the composition of the basis-change Clifford `CircuitOp` c with the destination PauliOp d and c†, such that p = c·d·c†, up to global phase. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to convert. + +**Returns** + +The converted Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### get\_cob\_circuit + + + +`get_cob_circuit(origin)` + +Construct an Operator which maps the +1 and -1 eigenvectors of the origin Pauli to the +1 and -1 eigenvectors of the destination Pauli. It does so by + +1. converting any |i+⟩ or |i+⟩ eigenvector bits in the origin to |+⟩ and |-⟩ with S†s, then +2. converting any |+⟩ or |+⟩ eigenvector bits in the converted origin to |0⟩ and |1⟩ with Hs, then +3. writing the parity of the significant (Z-measured, rather than I) bits in the origin to a single “origin anchor bit,” using cnots, which will hold the parity of these bits, +4. swapping the parity of the pauli anchor bit into a destination anchor bit using a swap gate (only if they are different, if there are any bits which are significant in both origin and dest, we set both anchors to one of these bits to avoid a swap). +5. writing the parity of the destination anchor bit into the other significant bits of the destination, +6. converting the |0⟩ and |1⟩ significant eigenvector bits to |+⟩ and |-⟩ eigenvector bits in the destination where the destination demands it (e.g. pauli.x == true for a bit), using Hs 8) converting the |+⟩ and |-⟩ significant eigenvector bits to |i+⟩ and |i-⟩ eigenvector bits in the destination where the destination demands it (e.g. pauli.x == true and pauli.z == true for a bit), using Ss + +**Parameters** + +**origin** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – The `Pauli` or `PauliOp` to map. + +**Returns** + +A tuple of a `PrimitiveOp` which equals the basis change mapping and a `PauliOp` which equals the destination basis. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Attempting to convert from non-Pauli origin. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Attempting to change a non-identity Pauli to an identity Pauli, or vice versa. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp"), [*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")] + +### get\_diagonal\_pauli\_op + + + +`get_diagonal_pauli_op(pauli_op)` + +Get the diagonal `PualiOp` to which `pauli_op` could be rotated with only single-qubit operations. + +**Parameters** + +**pauli\_op** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – The `PauliOp` whose diagonal to compute. + +**Returns** + +The diagonal `PauliOp`. + +**Return type** + +[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") + +### get\_diagonalizing\_clifford + + + +`get_diagonalizing_clifford(pauli)` + +Construct a `CircuitOp` with only single-qubit gates which takes the eigenvectors of `pauli` to eigenvectors composed only of |0⟩ and |1⟩ tensor products. Equivalently, finds the basis-change circuit to take `pauli` to a diagonal `PauliOp` composed only of Z and I tensor products. + +Note, underlying Pauli bits are in Qiskit endianness, so we need to reverse before we begin composing with Operator flow. + +**Parameters** + +**pauli** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – the `Pauli` or `PauliOp` to whose diagonalizing circuit to compute. + +**Returns** + +The diagonalizing `CircuitOp`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### get\_tpb\_pauli + + + +`get_tpb_pauli(list_op)` + +Gets the Pauli (not `PauliOp`!) whose diagonalizing single-qubit rotations is a superset of the diagonalizing single-qubit rotations for each of the Paulis in `list_op`. TPB stands for Tensor Product Basis. + +**Parameters** + +**list\_op** ([*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp")) – the `ListOp` whose TPB Pauli to return. + +**Returns** + +The TBP Pauli. + +**Return type** + +[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") + +### measurement\_replacement\_fn + + + +`static measurement_replacement_fn(cob_instr_op, dest_pauli_op)` + +A built-in convenience replacement function which produces measurements isomorphic to an `OperatorStateFn` measurement holding the origin `PauliOp`. + +**Parameters** + +* **cob\_instr\_op** ([*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp")) – The basis-change `CircuitOp`. +* **dest\_pauli\_op** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") *|*[*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp")) – The destination Pauli type operator. + +**Returns** + +The `~StateFn @ CircuitOp` composition equivalent to a measurement by the original `PauliOp`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### operator\_replacement\_fn + + + +`static operator_replacement_fn(cob_instr_op, dest_pauli_op)` + +A built-in convenience replacement function which produces Operators isomorphic to the origin `PauliOp`. + +**Parameters** + +* **cob\_instr\_op** ([*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp")) – The basis-change `CircuitOp`. +* **dest\_pauli\_op** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") *|*[*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp")) – The destination `PauliOp`. + +**Returns** + +The `~CircuitOp @ PauliOp @ CircuitOp` composition isomorphic to the original `PauliOp`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### pad\_paulis\_to\_equal\_length + + + +`pad_paulis_to_equal_length(pauli_op1, pauli_op2)` + +If `pauli_op1` and `pauli_op2` do not act over the same number of qubits, pad identities to the end of the shorter of the two so they are of equal length. Padding is applied to the end of the Paulis. Note that the Terra represents Paulis in big-endian order, so this will appear as padding to the beginning of the Pauli x and z bit arrays. + +**Parameters** + +* **pauli\_op1** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – A pauli\_op to possibly pad. +* **pauli\_op2** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – A pauli\_op to possibly pad. + +**Returns** + +A tuple containing the padded PauliOps. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp"), [*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")] + +### statefn\_replacement\_fn + + + +`static statefn_replacement_fn(cob_instr_op, dest_pauli_op)` + +A built-in convenience replacement function which produces state functions isomorphic to an `OperatorStateFn` state function holding the origin `PauliOp`. + +**Parameters** + +* **cob\_instr\_op** ([*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp")) – The basis-change `CircuitOp`. +* **dest\_pauli\_op** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") *|*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") *|*[*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp")) – The destination Pauli type operator. + +**Returns** + +The `~CircuitOp @ StateFn` composition equivalent to a state function defined by the original `PauliOp`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.TwoQubitReduction.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.TwoQubitReduction.md new file mode 100644 index 00000000000..4fb8b3aebfa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.TwoQubitReduction.md @@ -0,0 +1,50 @@ +--- +title: TwoQubitReduction +description: API reference for qiskit.opflow.converters.TwoQubitReduction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.converters.TwoQubitReduction +--- + +# TwoQubitReduction + + + +`qiskit.opflow.converters.TwoQubitReduction(num_particles)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/converters/two_qubit_reduction.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: Two qubit reduction converter which eliminates the central and last qubit in a list of Pauli that has diagonal operators (Z,I) at those positions. + +Chemistry specific method: It can be used to taper two qubits in parity and binary-tree mapped fermionic Hamiltonians when the spin orbitals are ordered in two spin sectors, (block spin order) according to the number of particles in the system. + + + The class `qiskit.opflow.converters.two_qubit_reduction.TwoQubitReduction` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**num\_particles** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – number of particles, if it is a list, the first number is alpha and the second number if beta. + +## Methods + +### convert + + + +`convert(operator)` + +Converts the Operator to tapered one by Z2 symmetries. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – the operator + +**Returns** + +A new operator whose qubit number is reduced by 2. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.converters.md b/docs/api/qiskit/0.46/qiskit.opflow.converters.md new file mode 100644 index 00000000000..1e134768011 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.converters.md @@ -0,0 +1,52 @@ +--- +title: converters +description: API reference for qiskit.opflow.converters +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.converters +--- + + + + + +# qiskit.opflow\.converters + + + +## Converters + + + +`qiskit.opflow.converters` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +Converters are objects which manipulate Operators, usually traversing an Operator to change certain sub-Operators into a desired representation. Often the converted Operator is isomorphic or approximate to the original Operator in some way, but not always. For example, a converter may accept [`CircuitOp`](qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.CircuitOp") and return a [`SummedOp`](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp") of [`PauliOp`](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.PauliOp")’s representing the circuit unitary. Converters may not have polynomial space or time scaling in their operations. On the contrary, many converters, such as a [`MatrixExpectation`](qiskit.opflow.expectations.MatrixExpectation "qiskit.opflow.expectations.MatrixExpectation") or [`MatrixEvolution`](qiskit.opflow.evolutions.MatrixEvolution "qiskit.opflow.evolutions.MatrixEvolution"), which convert [`PauliOp`](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.PauliOp")’s to [`MatrixOp`](qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.MatrixOp")’s internally, will require time or space exponential in the number of qubits unless a clever trick is known (such as the use of sparse matrices). + + + Not all converters are in this module, as [`expectations`](qiskit.opflow.expectations#module-qiskit.opflow.expectations "qiskit.opflow.expectations") and [`evolutions`](qiskit.opflow.evolutions#module-qiskit.opflow.evolutions "qiskit.opflow.evolutions") are also converters. + + +### Converter Base Class + +The converter base class simply enforces the presence of a [`convert()`](qiskit.opflow.converters.ConverterBase#convert "qiskit.opflow.converters.ConverterBase.convert") method. + +| | | +| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.ConverterBase")() | Deprecated: Converters take an Operator and return a new Operator, generally isomorphic in some way with the first, but with certain desired properties. | + +### Converters + +In addition to the base class, directory holds a few miscellaneous converters which are used frequently around the Operator flow. + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`CircuitSampler`](qiskit.opflow.converters.CircuitSampler "qiskit.opflow.converters.CircuitSampler")(backend\[, statevector, ...]) | Deprecated: The CircuitSampler traverses an Operator and converts any CircuitStateFns into approximations of the state function by a DictStateFn or VectorStateFn using a quantum backend. | +| [`AbelianGrouper`](qiskit.opflow.converters.AbelianGrouper "qiskit.opflow.converters.AbelianGrouper")(\[traverse]) | Deprecated: The AbelianGrouper converts SummedOps into a sum of Abelian sums. | +| [`DictToCircuitSum`](qiskit.opflow.converters.DictToCircuitSum "qiskit.opflow.converters.DictToCircuitSum")(\[traverse, convert\_dicts, ...]) | Deprecated: Converts `DictStateFns` or `VectorStateFns` to equivalent `CircuitStateFns` or sums thereof. | +| [`PauliBasisChange`](qiskit.opflow.converters.PauliBasisChange "qiskit.opflow.converters.PauliBasisChange")(\[destination\_basis, ...]) | Deprecated: Converter for changing Paulis into other bases. | +| [`TwoQubitReduction`](qiskit.opflow.converters.TwoQubitReduction "qiskit.opflow.converters.TwoQubitReduction")(num\_particles) | Deprecated: Two qubit reduction converter which eliminates the central and last qubit in a list of Pauli that has diagonal operators (Z,I) at those positions. | + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionBase.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionBase.md new file mode 100644 index 00000000000..d1acbdd63fd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionBase.md @@ -0,0 +1,44 @@ +--- +title: EvolutionBase +description: API reference for qiskit.opflow.evolutions.EvolutionBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.EvolutionBase +--- + +# EvolutionBase + + + +`qiskit.opflow.evolutions.EvolutionBase`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/evolution_base.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Deprecated: A base for Evolution converters. Evolutions are converters which traverse an Operator tree, replacing any `EvolvedOp` e with a Schrodinger equation-style evolution `CircuitOp` equalling or approximating the matrix exponential of -i \* the Operator contained inside (e.primitive). The Evolutions are essentially implementations of Hamiltonian Simulation algorithms, including various methods for Trotterization. + + + The class `qiskit.opflow.evolutions.evolution_base.EvolutionBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### convert + + + +`abstract convert(operator)` + +Traverse the operator, replacing any `EvolutionOps` with their equivalent evolution `CircuitOps`. + +> **Args:** +> +> operator: The Operator to convert. + +**Returns** + +The converted Operator, with `EvolutionOps` replaced by `CircuitOps`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionFactory.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionFactory.md new file mode 100644 index 00000000000..5893c606076 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolutionFactory.md @@ -0,0 +1,48 @@ +--- +title: EvolutionFactory +description: API reference for qiskit.opflow.evolutions.EvolutionFactory +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.EvolutionFactory +--- + +# EvolutionFactory + + + +`qiskit.opflow.evolutions.EvolutionFactory`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/evolution_factory.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: A factory class for convenient automatic selection of an Evolution algorithm based on the Operator to be converted. + +## Methods + +### build + + + +`static build(operator=None)` + +A factory method for convenient automatic selection of an Evolution algorithm based on the Operator to be converted. + + + The method `qiskit.opflow.evolutions.evolution_factory.EvolutionFactory.build()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – the Operator being evolved + +**Returns** + +the `EvolutionBase` best suited to evolve operator. + +**Return type** + +[EvolutionBase](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.EvolutionBase") + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If operator is not of a composition for which we know the best Evolution method. + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolvedOp.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolvedOp.md new file mode 100644 index 00000000000..991107e42e4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.EvolvedOp.md @@ -0,0 +1,337 @@ +--- +title: EvolvedOp +description: API reference for qiskit.opflow.evolutions.EvolvedOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.EvolvedOp +--- + +# EvolvedOp + + + +`qiskit.opflow.evolutions.EvolvedOp(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/evolved_op.py "view source code") + +Bases: [`PrimitiveOp`](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +Deprecated: Class for wrapping Operator Evolutions for compilation (`convert`) by an EvolutionBase method later, essentially acting as a placeholder. Note that EvolvedOp is a weird case of PrimitiveOp. It happens to be that it fits into the PrimitiveOp interface nearly perfectly, and it essentially represents a placeholder for a PrimitiveOp later, even though it doesn’t actually hold a primitive object. We could have chosen for it to be an OperatorBase, but would have ended up copying and pasting a lot of code from PrimitiveOp. + + + The class `qiskit.opflow.evolutions.evolved_op.EvolvedOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The operator being wrapped to signify evolution later. +* **coeff** – A coefficient multiplying the operator + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`PrimitiveOp` + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*EvolvedOp*](#qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.evolved_op.EvolvedOp") | [*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*EvolvedOp*](#qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.evolved_op.EvolvedOp") + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*EvolvedOp*](#qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.evolved_op.EvolvedOp") | [*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### log\_i + + + +`log_i(massive=False)` + +Return a `MatrixOp` equivalent to log(H)/-i for this operator H. This function is the effective inverse of exp\_i, equivalent to finding the Hermitian Operator which produces self when exponentiated. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`permute(permutation)` + +Permutes the qubits of the operator. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j should be permuted to position permutation\[j]. + +**Returns** + +A new OperatorBase containing the permuted operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*EvolvedOp*](#qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.evolved_op.EvolvedOp") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*EvolvedOp*](#qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.evolved_op.EvolvedOp") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_instruction + + + +`to_instruction(massive=False)` + +Returns an `Instruction` equivalent to this Operator. + +**Return type** + +[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Returns a `MatrixOp` equivalent to this Operator. + +**Return type** + +[*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") | [*MatrixOp*](qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.matrix_op.MatrixOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.MatrixEvolution.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.MatrixEvolution.md new file mode 100644 index 00000000000..2314e9f47a2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.MatrixEvolution.md @@ -0,0 +1,44 @@ +--- +title: MatrixEvolution +description: API reference for qiskit.opflow.evolutions.MatrixEvolution +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.MatrixEvolution +--- + +# MatrixEvolution + + + +`qiskit.opflow.evolutions.MatrixEvolution`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/matrix_evolution.py "view source code") + +Bases: [`EvolutionBase`](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.evolution_base.EvolutionBase") + +Deprecated: Performs Evolution by classical matrix exponentiation, constructing a circuit with `UnitaryGates` or `HamiltonianGates` containing the exponentiation of the Operator. + + + The class `qiskit.opflow.evolutions.matrix_evolution.MatrixEvolution` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### convert + + + +`convert(operator)` + +Traverse the operator, replacing `EvolvedOps` with `CircuitOps` containing `UnitaryGates` or `HamiltonianGates` (if self.coeff is a `ParameterExpression`) equalling the exponentiation of -i \* operator. This is done by converting the `EvolvedOp.primitive` to a `MatrixOp` and simply calling `.exp_i()` on that. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to convert. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.PauliTrotterEvolution.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.PauliTrotterEvolution.md new file mode 100644 index 00000000000..789f15d0a5e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.PauliTrotterEvolution.md @@ -0,0 +1,96 @@ +--- +title: PauliTrotterEvolution +description: API reference for qiskit.opflow.evolutions.PauliTrotterEvolution +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.PauliTrotterEvolution +--- + +# PauliTrotterEvolution + + + +`qiskit.opflow.evolutions.PauliTrotterEvolution(trotter_mode='trotter', reps=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/pauli_trotter_evolution.py "view source code") + +Bases: [`EvolutionBase`](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.evolution_base.EvolutionBase") + +Deprecated: An Evolution algorithm replacing exponentiated sums of Paulis by changing them each to the Z basis, rotating with an rZ, changing back, and Trotterizing. + +More specifically, we compute basis change circuits for each Pauli into a single-qubit Z, evolve the Z by the desired evolution time with an rZ gate, and change the basis back using the adjoint of the original basis change circuit. For sums of Paulis, the individual Pauli evolution circuits are composed together by Trotterization scheme. + + + The class `qiskit.opflow.evolutions.pauli_trotter_evolution.PauliTrotterEvolution` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **trotter\_mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*TrotterizationBase*](qiskit.opflow.evolutions.TrotterizationBase "qiskit.opflow.evolutions.trotterizations.trotterization_base.TrotterizationBase") *| None*) – A string (‘trotter’, ‘suzuki’, or ‘qdrift’) to pass to the TrotterizationFactory, or a TrotterizationBase, indicating how to combine individual Pauli evolution circuits to equal the exponentiation of the Pauli sum. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – How many Trotterization repetitions to make, to improve the approximation accuracy. +* **evolution.** (*# TODO uncomment when we implement Abelian grouped*) – +* **group\_paulis** (*#*) – Whether to group Pauli sums into Abelian +* **sub-groups** (*#*) – +* **group** (*so a single diagonalization circuit can be used for each*) – +* **Pauli.** (*# rather than each*) – + +## Attributes + + + +### trotter + +TrotterizationBase used to evolve SummedOps. + +## Methods + +### convert + + + +`convert(operator)` + +Traverse the operator, replacing `EvolvedOps` with `CircuitOps` containing Trotterized evolutions equalling the exponentiation of -i \* operator. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to convert. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### evolution\_for\_abelian\_paulisum + + + +`evolution_for_abelian_paulisum(op_sum)` + +Evolution for abelian pauli sum + +**Return type** + +[*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +### evolution\_for\_pauli + + + +`evolution_for_pauli(pauli_op)` + +Compute evolution Operator for a single Pauli using a `PauliBasisChange`. + +**Parameters** + +**pauli\_op** ([*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp")) – The `PauliOp` to evolve. + +**Returns** + +A `PrimitiveOp`, either the evolution `CircuitOp` or a `PauliOp` equal to the identity if pauli\_op is the identity. + +**Return type** + +[*PrimitiveOp*](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.QDrift.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.QDrift.md new file mode 100644 index 00000000000..efb089f3120 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.QDrift.md @@ -0,0 +1,60 @@ +--- +title: QDrift +description: API reference for qiskit.opflow.evolutions.QDrift +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.QDrift +--- + +# QDrift + + + +`qiskit.opflow.evolutions.QDrift(reps=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/trotterizations/qdrift.py "view source code") + +Bases: [`TrotterizationBase`](qiskit.opflow.evolutions.TrotterizationBase "qiskit.opflow.evolutions.trotterizations.trotterization_base.TrotterizationBase") + +Deprecated: The QDrift Trotterization method, which selects each each term in the Trotterization randomly, with a probability proportional to its weight. Based on the work of Earl Campbell in [https://arxiv.org/abs/1811.08017](https://arxiv.org/abs/1811.08017). + + + The class `qiskit.opflow.evolutions.trotterizations.qdrift.QDrift` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to repeat the Trotterization circuit. + +## Attributes + + + +### reps + +The number of repetitions to use in the Trotterization, improving the approximation accuracy. + +## Methods + +### convert + + + +`convert(operator)` + +Convert a `SummedOp` into a `ComposedOp` or `CircuitOp` representing an approximation of e^-i\*\`\`op\_sum\`\`. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `SummedOp` to evolve. + +**Returns** + +The Operator approximating op\_sum’s evolution. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – A non-SummedOps Operator is passed into `convert`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.Suzuki.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.Suzuki.md new file mode 100644 index 00000000000..4b73ffa457f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.Suzuki.md @@ -0,0 +1,69 @@ +--- +title: Suzuki +description: API reference for qiskit.opflow.evolutions.Suzuki +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.Suzuki +--- + +# Suzuki + + + +`qiskit.opflow.evolutions.Suzuki(reps=1, order=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/trotterizations/suzuki.py "view source code") + +Bases: [`TrotterizationBase`](qiskit.opflow.evolutions.TrotterizationBase "qiskit.opflow.evolutions.trotterizations.trotterization_base.TrotterizationBase") + +Deprecated: Suzuki Trotter expansion, composing the evolution circuits of each Operator in the sum together by a recursive “bookends” strategy, repeating the whole composed circuit `reps` times. + +Detailed in [https://arxiv.org/pdf/quant-ph/0508139.pdf](https://arxiv.org/pdf/quant-ph/0508139.pdf). + + + The class `qiskit.opflow.evolutions.trotterizations.suzuki.Suzuki` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to repeat the expansion circuit. +* **order** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The order of the expansion to perform. + +## Attributes + + + +### order + +returns order + + + +### reps + +The number of repetitions to use in the Trotterization, improving the approximation accuracy. + +## Methods + +### convert + + + +`convert(operator)` + +Convert a `SummedOp` into a `ComposedOp` or `CircuitOp` representing an approximation of e^-i\*\`\`op\_sum\`\`. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `SummedOp` to evolve. + +**Returns** + +The Operator approximating op\_sum’s evolution. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – A non-SummedOps Operator is passed into `convert`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.Trotter.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.Trotter.md new file mode 100644 index 00000000000..54c4cd95666 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.Trotter.md @@ -0,0 +1,40 @@ +--- +title: Trotter +description: API reference for qiskit.opflow.evolutions.Trotter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.Trotter +--- + +# Trotter + + + +`qiskit.opflow.evolutions.Trotter(reps=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/trotterizations/trotter.py "view source code") + +Bases: [`Suzuki`](qiskit.opflow.evolutions.Suzuki "qiskit.opflow.evolutions.trotterizations.suzuki.Suzuki") + +Deprecated: Simple Trotter expansion, composing the evolution circuits of each Operator in the sum together `reps` times and dividing the evolution time of each by `reps`. + + + The class `qiskit.opflow.evolutions.trotterizations.trotter.Trotter` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to repeat the Trotterization circuit. + +## Attributes + + + +### order + +returns order + + + +### reps + +The number of repetitions to use in the Trotterization, improving the approximation accuracy. + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationBase.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationBase.md new file mode 100644 index 00000000000..df4299e6e1a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationBase.md @@ -0,0 +1,56 @@ +--- +title: TrotterizationBase +description: API reference for qiskit.opflow.evolutions.TrotterizationBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.TrotterizationBase +--- + +# TrotterizationBase + + + +`qiskit.opflow.evolutions.TrotterizationBase(reps=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/trotterizations/trotterization_base.py "view source code") + +Bases: [`EvolutionBase`](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.evolution_base.EvolutionBase") + +Deprecated: A base for Trotterization methods, algorithms for approximating exponentiations of operator sums by compositions of exponentiations. + + + The class `qiskit.opflow.evolutions.trotterizations.trotterization_base.TrotterizationBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Attributes + + + +### reps + +The number of repetitions to use in the Trotterization, improving the approximation accuracy. + +## Methods + +### convert + + + +`abstract convert(operator)` + +Convert a `SummedOp` into a `ComposedOp` or `CircuitOp` representing an approximation of e^-i\*\`\`op\_sum\`\`. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `SummedOp` to evolve. + +**Returns** + +The Operator approximating op\_sum’s evolution. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – A non-SummedOps Operator is passed into `convert`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationFactory.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationFactory.md new file mode 100644 index 00000000000..34f6052a78b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.TrotterizationFactory.md @@ -0,0 +1,49 @@ +--- +title: TrotterizationFactory +description: API reference for qiskit.opflow.evolutions.TrotterizationFactory +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.evolutions.TrotterizationFactory +--- + +# TrotterizationFactory + + + +`qiskit.opflow.evolutions.TrotterizationFactory`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/evolutions/trotterizations/trotterization_factory.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: A factory for conveniently creating TrotterizationBase instances. + +## Methods + +### build + + + +`static build(mode='trotter', reps=1)` + +A factory for conveniently creating TrotterizationBase instances. + + + The method `qiskit.opflow.evolutions.trotterizations.trotterization_factory.TrotterizationFactory.build()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – One of ‘trotter’, ‘suzuki’, ‘qdrift’ +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to repeat the Trotterization circuit. + +**Returns** + +The desired TrotterizationBase instance. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – A string not in \[‘trotter’, ‘suzuki’, ‘qdrift’] is given for mode. + +**Return type** + +[*TrotterizationBase*](qiskit.opflow.evolutions.TrotterizationBase "qiskit.opflow.evolutions.trotterizations.trotterization_base.TrotterizationBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.evolutions.md b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.md new file mode 100644 index 00000000000..1e9dc9e774c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.evolutions.md @@ -0,0 +1,61 @@ +--- +title: evolutions +description: API reference for qiskit.opflow.evolutions +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.evolutions +--- + + + + + +# qiskit.opflow\.evolutions + + + +## Operator Evolutions + + + +`qiskit.opflow.evolutions` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +Evolutions are converters which traverse an Operator tree, replacing any [`EvolvedOp`](qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.EvolvedOp") e with a Schrodinger equation-style evolution [`CircuitOp`](qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.CircuitOp") equalling or approximating the matrix exponential of -i \* the Operator contained inside (e.primitive). The Evolutions are essentially implementations of Hamiltonian Simulation algorithms, including various methods for Trotterization. + +The [`EvolvedOp`](qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.EvolvedOp") is simply a placeholder signifying that the Operator inside it should be converted to its exponential by the Evolution converter. All Operators (not [`state_fns`](qiskit.opflow.state_fns#module-qiskit.opflow.state_fns "qiskit.opflow.state_fns")) have `.exp_i()` methods which either return the exponential of the Operator directly, or an [`EvolvedOp`](qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.EvolvedOp") containing the Operator. + + + Evolutions work with parameterized Operator coefficients, so `my_expectation.convert((t * H).exp_i())`, where t is a scalar or Terra Parameter and H is an Operator, will produce a [`CircuitOp`](qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.CircuitOp") equivalent to e^iHt. + + +### Evolution Base Class + +The EvolutionBase class gives an interface for algorithms to ask for Evolutions as execution settings. For example, if an algorithm contains an Operator evolution step within it, such as [`QAOA`](qiskit.algorithms.QAOA "qiskit.algorithms.QAOA"), the algorithm can give the opportunity for the user to pass an EvolutionBase of their choice to be used in that evolution step. + +| | | +| ---------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| [`EvolutionBase`](qiskit.opflow.evolutions.EvolutionBase "qiskit.opflow.evolutions.EvolutionBase")() | Deprecated: A base for Evolution converters. | + +### Evolutions + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`EvolutionFactory`](qiskit.opflow.evolutions.EvolutionFactory "qiskit.opflow.evolutions.EvolutionFactory")() | Deprecated: A factory class for convenient automatic selection of an Evolution algorithm based on the Operator to be converted. | +| [`EvolvedOp`](qiskit.opflow.evolutions.EvolvedOp "qiskit.opflow.evolutions.EvolvedOp")(\*args, \*\*kwargs) | Deprecated: Class for wrapping Operator Evolutions for compilation (`convert`) by an EvolutionBase method later, essentially acting as a placeholder. | +| [`MatrixEvolution`](qiskit.opflow.evolutions.MatrixEvolution "qiskit.opflow.evolutions.MatrixEvolution")() | Deprecated: Performs Evolution by classical matrix exponentiation, constructing a circuit with `UnitaryGates` or `HamiltonianGates` containing the exponentiation of the Operator. | +| [`PauliTrotterEvolution`](qiskit.opflow.evolutions.PauliTrotterEvolution "qiskit.opflow.evolutions.PauliTrotterEvolution")(\[trotter\_mode, reps]) | Deprecated: An Evolution algorithm replacing exponentiated sums of Paulis by changing them each to the Z basis, rotating with an rZ, changing back, and Trotterizing. | + +### Trotterizations + +| | | +| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`TrotterizationBase`](qiskit.opflow.evolutions.TrotterizationBase "qiskit.opflow.evolutions.TrotterizationBase")(\[reps]) | Deprecated: A base for Trotterization methods, algorithms for approximating exponentiations of operator sums by compositions of exponentiations. | +| [`TrotterizationFactory`](qiskit.opflow.evolutions.TrotterizationFactory "qiskit.opflow.evolutions.TrotterizationFactory")() | Deprecated: A factory for conveniently creating TrotterizationBase instances. | +| [`Trotter`](qiskit.opflow.evolutions.Trotter "qiskit.opflow.evolutions.Trotter")(\[reps]) | Deprecated: Simple Trotter expansion, composing the evolution circuits of each Operator in the sum together `reps` times and dividing the evolution time of each by `reps`. | +| [`Suzuki`](qiskit.opflow.evolutions.Suzuki "qiskit.opflow.evolutions.Suzuki")(\[reps, order]) | Deprecated: Suzuki Trotter expansion, composing the evolution circuits of each Operator in the sum together by a recursive "bookends" strategy, repeating the whole composed circuit `reps` times. | +| [`QDrift`](qiskit.opflow.evolutions.QDrift "qiskit.opflow.evolutions.QDrift")(\[reps]) | Deprecated: The QDrift Trotterization method, which selects each each term in the Trotterization randomly, with a probability proportional to its weight. | + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.AerPauliExpectation.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.AerPauliExpectation.md new file mode 100644 index 00000000000..c953da7ecdd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.AerPauliExpectation.md @@ -0,0 +1,64 @@ +--- +title: AerPauliExpectation +description: API reference for qiskit.opflow.expectations.AerPauliExpectation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.expectations.AerPauliExpectation +--- + +# AerPauliExpectation + + + +`qiskit.opflow.expectations.AerPauliExpectation`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/expectations/aer_pauli_expectation.py "view source code") + +Bases: [`ExpectationBase`](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") + +An Expectation converter for using Aer’s operator snapshot to take expectations of quantum state circuits over Pauli observables. + + + The class `qiskit.opflow.expectations.aer_pauli_expectation.AerPauliExpectation` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### compute\_variance + + + +`compute_variance(exp_op)` + +Compute the variance of the expectation estimator. Because Aer takes this expectation with matrix multiplication, the estimation is exact and the variance is always 0, but we need to return those values in a way which matches the Operator’s structure. + +**Parameters** + +**exp\_op** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The full expectation value Operator after sampling. + +**Returns** + +The variances or lists thereof (if exp\_op contains ListOps) of the expectation value estimation, equal to 0. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### convert + + + +`convert(operator)` + +Accept an Operator and return a new Operator with the Pauli measurements replaced by AerSnapshot-based expectation circuits. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator to convert. If it contains non-hermitian terms, the operator is decomposed into hermitian and anti-hermitian parts. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.CVaRExpectation.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.CVaRExpectation.md new file mode 100644 index 00000000000..5df1539ef46 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.CVaRExpectation.md @@ -0,0 +1,89 @@ +--- +title: CVaRExpectation +description: API reference for qiskit.opflow.expectations.CVaRExpectation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.expectations.CVaRExpectation +--- + +# CVaRExpectation + + + +`qiskit.opflow.expectations.CVaRExpectation(alpha, expectation=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/expectations/cvar_expectation.py "view source code") + +Bases: [`ExpectationBase`](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") + +Deprecated: Compute the Conditional Value at Risk (CVaR) expectation value. + +The standard approach to calculating the expectation value of a Hamiltonian w\.r.t. a state is to take the sample mean of the measurement outcomes. This corresponds to an estimator of the energy. However in several problem settings with a diagonal Hamiltonian, e.g. in combinatorial optimization where the Hamiltonian encodes a cost function, we are not interested in calculating the energy but in the lowest possible value we can find. + +To this end, we might consider using the best observed sample as a cost function during variational optimization. The issue here, is that this can result in a non-smooth optimization surface. To resolve this issue, we can smooth the optimization surface by using not just the best observed sample, but instead average over some fraction of best observed samples. This is exactly what the CVaR estimator accomplishes \[1]. + +It is empirically shown, that this can lead to faster convergence for combinatorial optimization problems. + +Let $\alpha$ be a real number in $[0,1]$ which specifies the fraction of best observed samples which are used to compute the objective function. Observe that if $\alpha = 1$, CVaR is equivalent to a standard expectation value. Similarly, if $\alpha = 0$, then CVaR corresponds to using the best observed sample. Intermediate values of $\alpha$ interpolate between these two objective functions. + +**References** + +**\[1]: Barkoutsos, P. K., Nannicini, G., Robert, A., Tavernelli, I., and Woerner, S.,** + +“Improving Variational Quantum Optimization using CVaR” [arXiv:1907.04769](https://arxiv.org/abs/1907.04769) + + + The class `qiskit.opflow.expectations.cvar_expectation.CVaRExpectation` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The alpha value describing the quantile considered in the expectation value. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") *| None*) – An expectation object to compute the expectation value. Defaults to the PauliExpectation calculation. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If the `expectation` is an AerPauliExpecation. + +## Methods + +### compute\_variance + + + +`compute_variance(exp_op)` + +Returns the variance of the CVaR calculation + +**Parameters** + +**exp\_op** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator whose evaluation yields an expectation of some StateFn against a diagonal observable. + +**Returns** + +**The variance of the CVaR estimate corresponding to the converted** + +exp\_op. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the exp\_op does not correspond to an expectation value. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### convert + + + +`convert(operator)` + +Return an expression that computes the CVaR expectation upon calling `eval`. :param operator: The operator to convert. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationBase.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationBase.md new file mode 100644 index 00000000000..d5ddd286108 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationBase.md @@ -0,0 +1,64 @@ +--- +title: ExpectationBase +description: API reference for qiskit.opflow.expectations.ExpectationBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.expectations.ExpectationBase +--- + +# ExpectationBase + + + +`qiskit.opflow.expectations.ExpectationBase`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/expectations/expectation_base.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: A base for Expectation value converters. Expectations are converters which enable the computation of the expectation value of an Observable with respect to some state function. They traverse an Operator tree, replacing OperatorStateFn measurements with equivalent measurements which are more amenable to computation on quantum or classical hardware. For example, if one would like to measure the expectation value of an Operator `o` expressed as a sum of Paulis with respect to some state function, but only has access to diagonal measurements on Quantum hardware, we can create a measurement \~StateFn(o), use a `PauliExpectation` to convert it to a diagonal measurement and circuit pre-rotations to a append to the state, and sample this circuit on Quantum hardware with a CircuitSampler. All in all, this would be: `my_sampler.convert(my_expect.convert(~StateFn(o)) @ my_state).eval()`. + + + The class `qiskit.opflow.expectations.expectation_base.ExpectationBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### compute\_variance + + + +`abstract compute_variance(exp_op)` + +Compute the variance of the expectation estimator. + +**Parameters** + +**exp\_op** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The full expectation value Operator after sampling. + +**Returns** + +The variances or lists thereof (if exp\_op contains ListOps) of the expectation value estimation. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") | [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### convert + + + +`abstract convert(operator)` + +Accept an Operator and return a new Operator with the measurements replaced by alternate methods to compute the expectation value. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator to convert. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationFactory.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationFactory.md new file mode 100644 index 00000000000..4f2df062d28 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.ExpectationFactory.md @@ -0,0 +1,50 @@ +--- +title: ExpectationFactory +description: API reference for qiskit.opflow.expectations.ExpectationFactory +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.expectations.ExpectationFactory +--- + +# ExpectationFactory + + + +`qiskit.opflow.expectations.ExpectationFactory`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/expectations/expectation_factory.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: factory class for convenient automatic selection of an Expectation based on the Operator to be converted and backend used to sample the expectation value. + +## Methods + +### build + + + +`static build(operator, backend=None, include_custom=True)` + +A factory method for convenient automatic selection of an Expectation based on the Operator to be converted and backend used to sample the expectation value. + + + The method `qiskit.opflow.expectations.expectation_factory.ExpectationFactory.build()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator whose expectation value will be taken. +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *|*[*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.quantum_instance.QuantumInstance") *| None*) – The backend which will be used to sample the expectation value. +* **include\_custom** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the factory will include the (Aer) specific custom expectations if their behavior against the backend might not be as expected. For instance when using Aer qasm\_simulator with paulis the Aer snapshot can be used but the outcome lacks shot noise and hence does not intuitively behave overall as people might expect when choosing a qasm\_simulator. It is however fast as long as the more state vector like behavior is acceptable. + +**Returns** + +The expectation algorithm which best fits the Operator and backend. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If operator is not of a composition for which we know the best Expectation method. + +**Return type** + +[*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.MatrixExpectation.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.MatrixExpectation.md new file mode 100644 index 00000000000..a2d9345e208 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.MatrixExpectation.md @@ -0,0 +1,64 @@ +--- +title: MatrixExpectation +description: API reference for qiskit.opflow.expectations.MatrixExpectation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.expectations.MatrixExpectation +--- + +# MatrixExpectation + + + +`qiskit.opflow.expectations.MatrixExpectation`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/expectations/matrix_expectation.py "view source code") + +Bases: [`ExpectationBase`](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") + +An Expectation converter which converts Operator measurements to be matrix-based so they can be evaluated by matrix multiplication. + + + The class `qiskit.opflow.expectations.matrix_expectation.MatrixExpectation` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### compute\_variance + + + +`compute_variance(exp_op)` + +Compute the variance of the expectation estimator. Because this expectation works by matrix multiplication, the estimation is exact and the variance is always 0, but we need to return those values in a way which matches the Operator’s structure. + +**Parameters** + +**exp\_op** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The full expectation value Operator. + +**Returns** + +The variances or lists thereof (if exp\_op contains ListOps) of the expectation value estimation, equal to 0. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### convert + + + +`convert(operator)` + +Accept an Operator and return a new Operator with the Pauli measurements replaced by Matrix based measurements. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator to convert. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.PauliExpectation.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.PauliExpectation.md new file mode 100644 index 00000000000..b1aee536e3b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.PauliExpectation.md @@ -0,0 +1,68 @@ +--- +title: PauliExpectation +description: API reference for qiskit.opflow.expectations.PauliExpectation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.expectations.PauliExpectation +--- + +# PauliExpectation + + + +`qiskit.opflow.expectations.PauliExpectation(group_paulis=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/expectations/pauli_expectation.py "view source code") + +Bases: [`ExpectationBase`](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") + +An Expectation converter for Pauli-basis observables by changing Pauli measurements to a diagonal (\{Z, I}^n) basis and appending circuit post-rotations to the measured state function. Optionally groups the Paulis with the same post-rotations (those that commute with one another, or form Abelian groups) into single measurements to reduce circuit execution overhead. + + + The class `qiskit.opflow.expectations.pauli_expectation.PauliExpectation` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**group\_paulis** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to group the Pauli measurements into commuting sums, which all have the same diagonalizing circuit. + +## Methods + +### compute\_variance + + + +`compute_variance(exp_op)` + +Compute the variance of the expectation estimator. + +**Parameters** + +**exp\_op** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The full expectation value Operator after sampling. + +**Returns** + +The variances or lists thereof (if exp\_op contains ListOps) of the expectation value estimation. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### convert + + + +`convert(operator)` + +Accepts an Operator and returns a new Operator with the Pauli measurements replaced by diagonal Pauli post-rotation based measurements so they can be evaluated by sampling and averaging. + +**Parameters** + +**operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator to convert. + +**Returns** + +The converted operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.expectations.md b/docs/api/qiskit/0.46/qiskit.opflow.expectations.md new file mode 100644 index 00000000000..50b011bb433 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.expectations.md @@ -0,0 +1,46 @@ +--- +title: expectations +description: API reference for qiskit.opflow.expectations +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.expectations +--- + + + + + +# qiskit.opflow\.expectations + + + +## Expectations + + + +`qiskit.opflow.expectations` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +Expectations are converters which enable the computation of the expectation value of an Observable with respect to some state function. They traverse an Operator tree, replacing [`OperatorStateFn`](qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.OperatorStateFn") measurements with equivalent measurements which are more amenable to computation on quantum or classical hardware. For example, if one would like to measure the expectation value of an Operator `o` expressed as a sum of Paulis with respect to some state function, but only has access to diagonal measurements on Quantum hardware, we can create a measurement \~StateFn(o), use a [`PauliExpectation`](qiskit.opflow.expectations.PauliExpectation "qiskit.opflow.expectations.PauliExpectation") to convert it to a diagonal measurement and circuit pre-rotations to append to the state, and sample this circuit on Quantum hardware with a [`CircuitSampler`](qiskit.opflow.converters.CircuitSampler "qiskit.opflow.converters.CircuitSampler"). All in all, this would be: `my_sampler.convert(my_expect.convert(~StateFn(o)) @ my_state).eval()`. + +### Expectation Base Class + +The ExpectationBase class gives an interface for algorithms to ask for Expectations as execution settings. For example, if an algorithm contains an expectation value step within it, such as [`VQE`](qiskit.algorithms.VQE "qiskit.algorithms.VQE"), the algorithm can give the opportunity for the user to pass an ExpectationBase of their choice to be used in that expectation value step. + +| | | +| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [`ExpectationBase`](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.ExpectationBase")() | Deprecated: A base for Expectation value converters. | + +### Expectations + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`ExpectationFactory`](qiskit.opflow.expectations.ExpectationFactory "qiskit.opflow.expectations.ExpectationFactory")() | Deprecated: factory class for convenient automatic selection of an Expectation based on the Operator to be converted and backend used to sample the expectation value. | +| [`AerPauliExpectation`](qiskit.opflow.expectations.AerPauliExpectation "qiskit.opflow.expectations.AerPauliExpectation")() | An Expectation converter for using Aer's operator snapshot to take expectations of quantum state circuits over Pauli observables. | +| [`MatrixExpectation`](qiskit.opflow.expectations.MatrixExpectation "qiskit.opflow.expectations.MatrixExpectation")() | An Expectation converter which converts Operator measurements to be matrix-based so they can be evaluated by matrix multiplication. | +| [`PauliExpectation`](qiskit.opflow.expectations.PauliExpectation "qiskit.opflow.expectations.PauliExpectation")(\[group\_paulis]) | An Expectation converter for Pauli-basis observables by changing Pauli measurements to a diagonal (\{Z, I}^n) basis and appending circuit post-rotations to the measured state function. | +| [`CVaRExpectation`](qiskit.opflow.expectations.CVaRExpectation "qiskit.opflow.expectations.CVaRExpectation")(alpha\[, expectation]) | Deprecated: Compute the Conditional Value at Risk (CVaR) expectation value. | + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitGradient.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitGradient.md new file mode 100644 index 00000000000..65d2d429cec --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitGradient.md @@ -0,0 +1,53 @@ +--- +title: CircuitGradient +description: API reference for qiskit.opflow.gradients.CircuitGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.CircuitGradient +--- + +# CircuitGradient + + + +`qiskit.opflow.gradients.CircuitGradient`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/circuit_gradients/circuit_gradient.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: Circuit to gradient operator converter. + +Converter for changing parameterized circuits into operators whose evaluation yields the gradient with respect to the circuit parameters. + +This is distinct from DerivativeBase converters which take gradients of composite operators and handle things like differentiating combo\_fn’s and enforcing product rules when operator coefficients are parameterized. + +CircuitGradient - uses quantum techniques to get derivatives of circuits DerivativeBase - uses classical techniques to differentiate operator flow data structures + + + The class `qiskit.opflow.gradients.circuit_gradients.circuit_gradient.CircuitGradient` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### convert + + + +`abstract convert(operator, params=None)` + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator we are taking the gradient of +* **params** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]] | None*) – The parameters we are taking the gradient wrt: ω If a ParameterExpression, ParameterVector or List\[ParameterExpression] is given, then the 1st order derivative of the operator is calculated. If a Tuple\[ParameterExpression, ParameterExpression] or List\[Tuple\[ParameterExpression, ParameterExpression]] is given, then the 2nd order derivative of the operator is calculated. + +**Returns** + +An operator whose evaluation yields the Gradient. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitQFI.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitQFI.md new file mode 100644 index 00000000000..faf06323354 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.CircuitQFI.md @@ -0,0 +1,53 @@ +--- +title: CircuitQFI +description: API reference for qiskit.opflow.gradients.CircuitQFI +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.CircuitQFI +--- + +# CircuitQFI + + + +`qiskit.opflow.gradients.CircuitQFI`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/circuit_qfis/circuit_qfi.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: Circuit to Quantum Fisher Information operator converter. + +Converter for changing parameterized circuits into operators whose evaluation yields Quantum Fisher Information metric tensor with respect to the given circuit parameters + +This is distinct from DerivativeBase converters which take gradients of composite operators and handle things like differentiating combo\_fn’s and enforcing product rules when operator coefficients are parameterized. + +CircuitQFI - uses quantum techniques to get the QFI of circuits DerivativeBase - uses classical techniques to differentiate opflow data structures + + + The class `qiskit.opflow.gradients.circuit_qfis.circuit_qfi.CircuitQFI` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### convert + + + +`abstract convert(operator, params)` + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator corresponding to the quantum state $|\psi(\omega)\rangle$ for which we compute the QFI. +* **params** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]*) – The parameters $\omega$ with respect to which we are computing the QFI. + +**Returns** + +An operator whose evaluation yields the QFI metric tensor. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.DerivativeBase.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.DerivativeBase.md new file mode 100644 index 00000000000..b8d8c50415c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.DerivativeBase.md @@ -0,0 +1,102 @@ +--- +title: DerivativeBase +description: API reference for qiskit.opflow.gradients.DerivativeBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.DerivativeBase +--- + +# DerivativeBase + + + +`qiskit.opflow.gradients.DerivativeBase`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/derivative_base.py "view source code") + +Bases: [`ConverterBase`](qiskit.opflow.converters.ConverterBase "qiskit.opflow.converters.converter_base.ConverterBase") + +Deprecated: Base class for differentiating opflow objects. + +Converter for differentiating opflow objects and handling things like properly differentiating combo\_fn’s and enforcing product rules when operator coefficients are parameterized. + +This is distinct from CircuitGradient converters which use quantum techniques such as parameter shifts and linear combination of unitaries to compute derivatives of circuits. + +CircuitGradient - uses quantum techniques to get derivatives of circuits DerivativeBase - uses classical techniques to differentiate opflow data structures + + + The class `qiskit.opflow.gradients.derivative_base.DerivativeBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Methods + +### convert + + + +`abstract convert(operator, params=None)` + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator we are taking the gradient, Hessian or QFI of +* **params** ([*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] | None*) – The parameters we are taking the gradient, Hessian or QFI with respect to. + +**Returns** + +An operator whose evaluation yields the gradient, Hessian or QFI. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### gradient\_wrapper + + + +`gradient_wrapper(operator, bind_params, grad_params=None, backend=None, expectation=None)` + +Get a callable function which provides the respective gradient, Hessian or QFI for given parameter values. This callable can be used as gradient function for optimizers. + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator for which we want to get the gradient, Hessian or QFI. +* **bind\_params** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]*) – The operator parameters to which the parameter values are assigned. +* **grad\_params** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]] | None*) – The parameters with respect to which we are taking the gradient, Hessian or QFI. If grad\_params = None, then grad\_params = bind\_params +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *|*[*QuantumInstance*](qiskit.utils.QuantumInstance "qiskit.utils.quantum_instance.QuantumInstance") *| None*) – The quantum backend or QuantumInstance to use to evaluate the gradient, Hessian or QFI. +* **expectation** ([*ExpectationBase*](qiskit.opflow.expectations.ExpectationBase "qiskit.opflow.expectations.expectation_base.ExpectationBase") *| None*) – The expectation converter to be used. If none is set then PauliExpectation() is used. + +**Returns** + +Function to compute a gradient, Hessian or QFI. The function takes an iterable as argument which holds the parameter values. + +**Return type** + +[*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")\[\[[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")], [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")] + +### parameter\_expression\_grad + + + +`static parameter_expression_grad(param_expr, param)` + +Get the derivative of a parameter expression w\.r.t. the given parameter. + + + The method `qiskit.opflow.gradients.derivative_base.DerivativeBase.parameter_expression_grad()` is deprecated as of qiskit-terra 0.18.0. It will be removed in the Qiskit 1.0 release. Instead, use the ParameterExpression.gradient method. + + +**Parameters** + +* **param\_expr** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The Parameter Expression for which we compute the derivative +* **param** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Parameter w\.r.t. which we want to take the derivative + +**Returns** + +ParameterExpression representing the gradient of param\_expr w\.r.t. param + +**Return type** + +[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") | [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.Gradient.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.Gradient.md new file mode 100644 index 00000000000..885c06ef981 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.Gradient.md @@ -0,0 +1,90 @@ +--- +title: Gradient +description: API reference for qiskit.opflow.gradients.Gradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.Gradient +--- + +# Gradient + + + +`qiskit.opflow.gradients.Gradient(grad_method='param_shift', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/gradient.py "view source code") + +Bases: [`GradientBase`](qiskit.opflow.gradients.GradientBase "qiskit.opflow.gradients.gradient_base.GradientBase") + +Deprecated: Convert an operator expression to the first-order gradient. + + + The class `qiskit.opflow.gradients.gradient.Gradient` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Attributes + + + +### grad\_method + +Returns `CircuitGradient`. + +**Returns** + +`CircuitGradient`. + +## Methods + +### convert + + + +`convert(operator, params=None)` + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator we are taking the gradient of. +* **params** ([*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] | None*) – The parameters we are taking the gradient with respect to. If not explicitly passed, they are inferred from the operator and sorted by name. + +**Returns** + +An operator whose evaluation yields the Gradient. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `operator` is not parameterized. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### get\_gradient + + + +`get_gradient(operator, params)` + +Get the gradient for the given operator w\.r.t. the given parameters + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator w\.r.t. which we take the gradient. +* **params** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]*) – Parameters w\.r.t. which we compute the gradient. + +**Returns** + +Operator which represents the gradient w\.r.t. the given params. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. +* [**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – If the coefficient of the operator could not be reduced to 1. +* [**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – If the differentiation of a combo\_fn requires JAX but the package is not installed. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the operator does not include a StateFn given by a quantum circuit +* [**Exception**](https://docs.python.org/3/library/exceptions.html#Exception "(in Python v3.12)") – Unintended code is reached +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – jax not installed + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.GradientBase.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.GradientBase.md new file mode 100644 index 00000000000..ca5fac01841 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.GradientBase.md @@ -0,0 +1,45 @@ +--- +title: GradientBase +description: API reference for qiskit.opflow.gradients.GradientBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.GradientBase +--- + +# GradientBase + + + +`qiskit.opflow.gradients.GradientBase(grad_method='param_shift', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/gradient_base.py "view source code") + +Bases: [`DerivativeBase`](qiskit.opflow.gradients.DerivativeBase "qiskit.opflow.gradients.derivative_base.DerivativeBase") + +Deprecated: Base class for first-order operator gradient. + +Convert an operator expression to the first-order gradient. + + + The class `qiskit.opflow.gradients.gradient_base.GradientBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **grad\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*CircuitGradient*](qiskit.opflow.gradients.CircuitGradient "qiskit.opflow.gradients.circuit_gradients.circuit_gradient.CircuitGradient")) – The method used to compute the state/probability gradient. Can be either `'param_shift'` or `'lin_comb'` or `'fin_diff'`. Ignored for gradients w\.r.t observable parameters. +* **kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Optional parameters for a CircuitGradient + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If method != `fin_diff` and `epsilon` is not None. + +## Attributes + + + +### grad\_method + +Returns `CircuitGradient`. + +**Returns** + +`CircuitGradient`. + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.Hessian.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.Hessian.md new file mode 100644 index 00000000000..7ec267a1205 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.Hessian.md @@ -0,0 +1,87 @@ +--- +title: Hessian +description: API reference for qiskit.opflow.gradients.Hessian +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.Hessian +--- + +# Hessian + + + +`qiskit.opflow.gradients.Hessian(hess_method='param_shift', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/hessian.py "view source code") + +Bases: [`HessianBase`](qiskit.opflow.gradients.HessianBase "qiskit.opflow.gradients.hessian_base.HessianBase") + +Deprecated: Compute the Hessian of an expected value. + + + The class `qiskit.opflow.gradients.hessian.Hessian` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Attributes + + + +### hess\_method + +Returns `CircuitGradient`. + +**Returns** + +`CircuitGradient`. + +## Methods + +### convert + + + +`convert(operator, params=None)` + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator for which we compute the Hessian +* **params** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *| None*) – The parameters we are computing the Hessian with respect to Either give directly the tuples/list of tuples for which the second order derivative is to be computed or give a list of parameters to build the full Hessian for those parameters. If not explicitly passed, the full Hessian is constructed. The parameters are then inferred from the operator and sorted by name. + +**Returns** + +An operator whose evaluation yields the Hessian + +**Return type** + +[OperatorBase](qiskit.opflow.OperatorBase "qiskit.opflow.OperatorBase") + +### get\_hessian + + + +`get_hessian(operator, params=None)` + +Get the Hessian for the given operator w\.r.t. the given parameters + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – Operator w\.r.t. which we take the Hessian. +* **params** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]] |* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] |* [*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *| None*) – Parameters w\.r.t. which we compute the Hessian. If not explicitly passed, the full Hessian is constructed. The parameters are then inferred from the operator and sorted by name. + +**Returns** + +Operator which represents the gradient w\.r.t. the given params. + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `operator` is not parameterized. +* [**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – If the coefficient of the operator could not be reduced to 1. +* [**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – If the differentiation of a combo\_fn requires JAX but the package is not installed. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the operator does not include a StateFn given by a quantum circuit +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the parameters were given in an unsupported format. +* [**Exception**](https://docs.python.org/3/library/exceptions.html#Exception "(in Python v3.12)") – Unintended code is reached +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – jax not installed + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.HessianBase.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.HessianBase.md new file mode 100644 index 00000000000..5b748e0e0fe --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.HessianBase.md @@ -0,0 +1,43 @@ +--- +title: HessianBase +description: API reference for qiskit.opflow.gradients.HessianBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.HessianBase +--- + +# HessianBase + + + +`qiskit.opflow.gradients.HessianBase(hess_method='param_shift', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/hessian_base.py "view source code") + +Bases: [`DerivativeBase`](qiskit.opflow.gradients.DerivativeBase "qiskit.opflow.gradients.derivative_base.DerivativeBase") + +Deprecated: Base class for the Hessian of an expected value. + + + The class `qiskit.opflow.gradients.hessian_base.HessianBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **hess\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*CircuitGradient*](qiskit.opflow.gradients.CircuitGradient "qiskit.opflow.gradients.circuit_gradients.circuit_gradient.CircuitGradient")) – The method used to compute the state/probability gradient. Can be either `'param_shift'` or `'lin_comb'` or `'fin_diff'`. Ignored for gradients w\.r.t observable parameters. +* **kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Optional parameters for a CircuitGradient + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If method != `fin_diff` and `epsilon` is not None. + +## Attributes + + + +### hess\_method + +Returns `CircuitGradient`. + +**Returns** + +`CircuitGradient`. + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.NaturalGradient.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.NaturalGradient.md new file mode 100644 index 00000000000..d894df8caba --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.NaturalGradient.md @@ -0,0 +1,119 @@ +--- +title: NaturalGradient +description: API reference for qiskit.opflow.gradients.NaturalGradient +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.NaturalGradient +--- + +# NaturalGradient + + + +`qiskit.opflow.gradients.NaturalGradient(grad_method='lin_comb', qfi_method='lin_comb_full', regularization=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/natural_gradient.py "view source code") + +Bases: [`GradientBase`](qiskit.opflow.gradients.GradientBase "qiskit.opflow.gradients.gradient_base.GradientBase") + +Deprecated: Convert an operator expression to the first-order gradient. + +Given an ill-posed inverse problem + +> x = arg min\{||Ax-C||^2} (1) + +one can use regularization schemes can be used to stabilize the system and find a numerical solution + +> x\_lambda = arg min\{||Ax-C||^2 + lambda\*R(x)} (2) + +where R(x) represents the penalization term. + + + The class `qiskit.opflow.gradients.natural_gradient.NaturalGradient` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **grad\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*CircuitGradient*](qiskit.opflow.gradients.CircuitGradient "qiskit.opflow.gradients.circuit_gradients.circuit_gradient.CircuitGradient")) – The method used to compute the state gradient. Can be either `'param_shift'` or `'lin_comb'` or `'fin_diff'`. +* **qfi\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*CircuitQFI*](qiskit.opflow.gradients.CircuitQFI "qiskit.opflow.gradients.circuit_qfis.circuit_qfi.CircuitQFI")) – The method used to compute the QFI. Can be either `'lin_comb_full'` or `'overlap_block_diag'` or `'overlap_diag'`. +* **regularization** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Use the following regularization with a least square method to solve the underlying system of linear equations Can be either None or `'ridge'` or `'lasso'` or `'perturb_diag'` `'ridge'` and `'lasso'` use an automatic optimal parameter search If regularization is None but the metric is ill-conditioned or singular then a least square solver is used without regularization +* **kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Optional parameters for a CircuitGradient + +## Attributes + + + +### grad\_method + +Returns `CircuitGradient`. + +**Returns** + +`CircuitGradient`. + + + +### qfi\_method + +Returns `CircuitQFI`. + +Returns: `CircuitQFI`. + + + +### regularization + +Returns the regularization option. + +Returns: the regularization option. + +## Methods + +### convert + + + +`convert(operator, params=None)` + +**Parameters** + +* **operator** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The operator we are taking the gradient of. +* **params** ([*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] | None*) – The parameters we are taking the gradient with respect to. If not explicitly passed, they are inferred from the operator and sorted by name. + +**Returns** + +An operator whose evaluation yields the NaturalGradient. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `operator` does not represent an expectation value or the quantum state is not `CircuitStateFn`. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `params` contains a parameter not present in `operator`. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `operator` is not parameterized. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### nat\_grad\_combo\_fn + + + +`static nat_grad_combo_fn(x, regularization=None)` + +Natural Gradient Function Implementation. + +**Parameters** + +* **x** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Iterable consisting of Gradient, Quantum Fisher Information. +* **regularization** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Regularization method. + +**Returns** + +Natural Gradient. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the gradient has imaginary components that are non-negligible. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.QFI.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.QFI.md new file mode 100644 index 00000000000..eab7417bdc2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.QFI.md @@ -0,0 +1,66 @@ +--- +title: QFI +description: API reference for qiskit.opflow.gradients.QFI +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.QFI +--- + +# QFI + + + +`qiskit.opflow.gradients.QFI(qfi_method='lin_comb_full')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/qfi.py "view source code") + +Bases: [`QFIBase`](qiskit.opflow.gradients.QFIBase "qiskit.opflow.gradients.qfi_base.QFIBase") + +Deprecated: Compute the Quantum Fisher Information (QFI). + +Computes the QFI given a pure, parameterized quantum state, where QFI is: + +$$ +\mathrm{QFI}_{kl}= 4 \mathrm{Re}[\langle \partial_k \psi | \partial_l \psi \rangle + − \langle\partial_k \psi | \psi \rangle \langle\psi | \partial_l \psi \rangle]. +$$ + + + The class `qiskit.opflow.gradients.qfi.QFI` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +## Attributes + + + +### qfi\_method + +Returns `CircuitQFI`. + +**Returns** + +`CircuitQFI`. + +## Methods + +### convert + + + +`convert(operator, params=None)` + +**Parameters** + +* **operator** ([*CircuitStateFn*](qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn")) – The operator corresponding to the quantum state |ψ(ω)〉for which we compute the QFI +* **params** ([*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.parametervector.ParameterVector") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*] | None*) – The parameters we are computing the QFI wrt: ω If not explicitly passed, they are inferred from the operator and sorted by name. + +**Returns** + +ListOp\[ListOp] where the operator at position k,l corresponds to QFI\_kl + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If operator is not parameterized. + +**Return type** + +[*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.QFIBase.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.QFIBase.md new file mode 100644 index 00000000000..552b5165d0f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.QFIBase.md @@ -0,0 +1,48 @@ +--- +title: QFIBase +description: API reference for qiskit.opflow.gradients.QFIBase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.gradients.QFIBase +--- + +# QFIBase + + + +`qiskit.opflow.gradients.QFIBase(qfi_method='lin_comb_full')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/gradients/qfi_base.py "view source code") + +Bases: [`DerivativeBase`](qiskit.opflow.gradients.DerivativeBase "qiskit.opflow.gradients.derivative_base.DerivativeBase") + +Deprecated: Base class for Quantum Fisher Information (QFI). + +Compute the Quantum Fisher Information (QFI) given a pure, parameterized quantum state. + +The QFI is: + +> \[QFI]kl= Re\[〈∂kψ|∂lψ〉−〈∂kψ|ψ〉〈ψ|∂lψ〉] \* 4. + + + The class `qiskit.opflow.gradients.qfi_base.QFIBase` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +**qfi\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*CircuitQFI*](qiskit.opflow.gradients.CircuitQFI "qiskit.opflow.gradients.circuit_qfis.circuit_qfi.CircuitQFI")) – The method used to compute the state/probability gradient. Can be either a [`CircuitQFI`](qiskit.opflow.gradients.CircuitQFI "qiskit.opflow.gradients.CircuitQFI") instance or one of the following pre-defined strings `'lin_comb_full'`, `` 'overlap_diag'` `` or `` 'overlap_block_diag'` ``. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if `qfi_method` is neither a `CircuitQFI` object nor one of the predefined strings. + +## Attributes + + + +### qfi\_method + +Returns `CircuitQFI`. + +**Returns** + +`CircuitQFI`. + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.gradients.md b/docs/api/qiskit/0.46/qiskit.opflow.gradients.md new file mode 100644 index 00000000000..982d7fe6c5a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.gradients.md @@ -0,0 +1,132 @@ +--- +title: gradients +description: API reference for qiskit.opflow.gradients +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.gradients +--- + + + + + +# qiskit.opflow\.gradients + + + +## Gradients + + + +`qiskit.opflow.gradients` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +Given an operator that represents either a quantum state resp. an expectation value, the gradient framework enables the evaluation of gradients, natural gradients, Hessians, as well as the Quantum Fisher Information. + +Suppose a parameterized quantum state |ψ(θ)〉 = V(θ)|ψ〉 with input state |ψ〉 and parameterized Ansatz V(θ), and an Operator O(ω). + +**Gradients** + +We want to compute one of: \* $d⟨ψ(θ)|O(ω)|ψ(θ)〉/ dω$ \* $d⟨ψ(θ)|O(ω)|ψ(θ)〉/ dθ$ \* $d⟨ψ(θ)|i〉⟨i|ψ(θ)〉/ dθ$ + +The last case corresponds to the gradient w\.r.t. the sampling probabilities of |ψ(θ). These gradients can be computed with different methods, i.e. a parameter shift, a linear combination of unitaries and a finite difference method. + +**Examples** + +```python +x = Parameter('x') +ham = x * X +a = Parameter('a') + +q = QuantumRegister(1) +qc = QuantumCircuit(q) +qc.h(q) +qc.p(params[0], q[0]) +op = ~StateFn(ham) @ CircuitStateFn(primitive=qc, coeff=1.) + +value_dict = {x: 0.1, a: np.pi / 4} + +ham_grad = Gradient(grad_method='param_shift').convert(operator=op, params=[x]) +ham_grad.assign_parameters(value_dict).eval() + +state_grad = Gradient(grad_method='lin_comb').convert(operator=op, params=[a]) +state_grad.assign_parameters(value_dict).eval() + +prob_grad = Gradient(grad_method='fin_diff').convert( + operator=CircuitStateFn(primitive=qc, coeff=1.), params=[a] +) +prob_grad.assign_parameters(value_dict).eval() +``` + +**Hessians** + +We want to compute one of: \* $d^2⟨ψ(θ)|O(ω)|ψ(θ)〉/ dω^2$ \* $d^2⟨ψ(θ)|O(ω)|ψ(θ)〉/ dθ^2$ \* $d^2⟨ψ(θ)|O(ω)|ψ(θ)〉/ dθ dω$ \* $d^2⟨ψ(θ)|i〉⟨i|ψ(θ)〉/ dθ^2$ + +The last case corresponds to the Hessian w\.r.t. the sampling probabilities of |ψ(θ)〉. Just as the first order gradients, the Hessians can be evaluated with different methods, i.e. a parameter shift, a linear combination of unitaries and a finite difference method. Given a tuple of parameters `Hessian().convert(op, param_tuple)` returns the value for the second order derivative. If a list of parameters is given `Hessian().convert(op, param_list)` returns the full Hessian for all the given parameters according to the given parameter order. + +**QFI** + +The Quantum Fisher Information QFI is a metric tensor which is representative for the representation capacity of a parameterized quantum state |ψ(θ)〉 = V(θ)|ψ〉 generated by an input state |ψ〉 and a parameterized Ansatz V(θ). The entries of the QFI for a pure state read $\mathrm{QFI}_{kl} = 4 \mathrm{Re}[〈∂kψ|∂lψ〉−〈∂kψ|ψ〉〈ψ|∂lψ〉]$. + +Just as for the previous derivative types, the QFI can be computed using different methods: a full representation based on a linear combination of unitaries implementation, a block-diagonal and a diagonal representation based on an overlap method. + +**Examples** + +```python +q = QuantumRegister(1) +qc = QuantumCircuit(q) +qc.h(q) +qc.p(params[0], q[0]) +op = ~StateFn(ham) @ CircuitStateFn(primitive=qc, coeff=1.) + +value_dict = {x: 0.1, a: np.pi / 4} + +qfi = QFI('lin_comb_full').convert( + operator=CircuitStateFn(primitive=qc, coeff=1.), params=[a] +) +qfi.assign_parameters(value_dict).eval() +``` + +**NaturalGradients** + +The natural gradient is a special gradient method which re-scales a gradient w\.r.t. a state parameter with the inverse of the corresponding Quantum Fisher Information (QFI) $\mathrm{QFI}^{-1} d⟨ψ(θ)|O(ω)|ψ(θ)〉/ dθ$. Hereby, we can choose a gradient as well as a QFI method and a regularization method which is used together with a least square solver instead of exact inversion of the QFI: + +**Examples** + +```python +op = ~StateFn(ham) @ CircuitStateFn(primitive=qc, coeff=1.) +nat_grad = NaturalGradient(grad_method='lin_comb, + qfi_method='lin_comb_full', + regularization='ridge').convert(operator=op, params=params) +``` + +The derivative classes come with a gradient\_wrapper() function which returns the corresponding callable and are thus compatible with the optimizers. + +### Base Classes + +| | | +| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| [`DerivativeBase`](qiskit.opflow.gradients.DerivativeBase "qiskit.opflow.gradients.DerivativeBase")() | Deprecated: Base class for differentiating opflow objects. | +| [`GradientBase`](qiskit.opflow.gradients.GradientBase "qiskit.opflow.gradients.GradientBase")(\[grad\_method]) | Deprecated: Base class for first-order operator gradient. | +| [`HessianBase`](qiskit.opflow.gradients.HessianBase "qiskit.opflow.gradients.HessianBase")(\[hess\_method]) | Deprecated: Base class for the Hessian of an expected value. | +| [`QFIBase`](qiskit.opflow.gradients.QFIBase "qiskit.opflow.gradients.QFIBase")(\[qfi\_method]) | Deprecated: Base class for Quantum Fisher Information (QFI). | + +### Converters + +| | | +| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [`CircuitGradient`](qiskit.opflow.gradients.CircuitGradient "qiskit.opflow.gradients.CircuitGradient")() | Deprecated: Circuit to gradient operator converter. | +| [`CircuitQFI`](qiskit.opflow.gradients.CircuitQFI "qiskit.opflow.gradients.CircuitQFI")() | Deprecated: Circuit to Quantum Fisher Information operator converter. | + +### Derivatives + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| [`Gradient`](qiskit.opflow.gradients.Gradient "qiskit.opflow.gradients.Gradient")(\[grad\_method]) | Deprecated: Convert an operator expression to the first-order gradient. | +| [`Hessian`](qiskit.opflow.gradients.Hessian "qiskit.opflow.gradients.Hessian")(\[hess\_method]) | Deprecated: Compute the Hessian of an expected value. | +| [`NaturalGradient`](qiskit.opflow.gradients.NaturalGradient "qiskit.opflow.gradients.NaturalGradient")(\[grad\_method, qfi\_method, ...]) | Deprecated: Convert an operator expression to the first-order gradient. | +| [`QFI`](qiskit.opflow.gradients.QFI "qiskit.opflow.gradients.QFI")(\[qfi\_method]) | Deprecated: Compute the Quantum Fisher Information (QFI). | + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.list_ops.ComposedOp.md b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.ComposedOp.md new file mode 100644 index 00000000000..19c3f912911 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.ComposedOp.md @@ -0,0 +1,254 @@ +--- +title: ComposedOp +description: API reference for qiskit.opflow.list_ops.ComposedOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.list_ops.ComposedOp +--- + +# ComposedOp + + + +`qiskit.opflow.list_ops.ComposedOp(oplist, coeff=1.0, abelian=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/list_ops/composed_op.py "view source code") + +Bases: [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +Deprecated: A class for lazily representing compositions of Operators. Often Operators cannot be efficiently composed with one another, but may be manipulated further so that they can be composed later. This class holds logic to indicate that the Operators in `oplist` are meant to be composed, and therefore if they reach a point in which they can be, such as after conversion to QuantumCircuits or matrices, they can be reduced by composition. + + + The class `qiskit.opflow.list_ops.composed_op.ComposedOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **oplist** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")*]*) – The Operators being composed. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient multiplying the operator +* **abelian** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Indicates whether the Operators in `oplist` are known to mutually commute. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### abelian + +Whether the Operators in `oplist` are known to commute with one another. + +**Returns** + +A bool indicating whether the `oplist` is Abelian. + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### coeffs + +Return a list of the coefficients of the operators listed. Raises exception for nested Listops. + + + +### combo\_fn + +The function defining how to combine `oplist` (or Numbers, or NumPy arrays) to produce the Operator’s underlying function. For example, SummedOp’s combination function is to add all of the Operators in `oplist`. + +**Returns** + +The combination function. + + + +### distributive + + + +### grad\_combo\_fn + +The gradient of `combo_fn`. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### oplist + +The list of `OperatorBases` defining the underlying function of this Operator. + +**Returns** + +The Operators defining the ListOp + + + +### parameters + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*ComposedOp*](#qiskit.opflow.list_ops.ComposedOp "qiskit.opflow.list_ops.composed_op.ComposedOp") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +ListOp’s eval recursively evaluates each Operator in `oplist`, and combines the results using the recombination function `combo_fn`. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function. + +**Returns** + +The output of the `oplist` Operators’ evaluation function, combined with the `combo_fn`. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Raises** + +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – Raised if called for a subclass which is not distributive. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Operators with mixed hierarchies, such as a ListOp containing both PrimitiveOps and ListOps, are not supported. +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – Attempting to call ListOp’s eval from a non-distributive subclass. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### non\_distributive\_reduce + + + +`non_distributive_reduce()` + +Reduce without attempting to expand all distributive compositions. + +**Returns** + +The reduced Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_circuit + + + +`to_circuit()` + +Returns the quantum circuit, representing the composed operator. + +**Returns** + +The circuit representation of the composed operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – for operators where a single underlying circuit can not be obtained. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.list_ops.ListOp.md b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.ListOp.md new file mode 100644 index 00000000000..be84b38a21d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.ListOp.md @@ -0,0 +1,518 @@ +--- +title: ListOp +description: API reference for qiskit.opflow.list_ops.ListOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.list_ops.ListOp +--- + +# ListOp + + + +`qiskit.opflow.list_ops.ListOp(oplist, combo_fn=None, coeff=1.0, abelian=False, grad_combo_fn=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/list_ops/list_op.py "view source code") + +Bases: [`OperatorBase`](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +Deprecated: A Class for manipulating List Operators, and parent class to `SummedOp`, `ComposedOp` and `TensoredOp`. + +List Operators are classes for storing and manipulating lists of Operators, State functions, or Measurements, and include some rule or `combo_fn` defining how the Operator functions of the list constituents should be combined to form to cumulative Operator function of the `ListOp`. For example, a `SummedOp` has an addition-based `combo_fn`, so once the Operators in its list are evaluated against some bitstring to produce a list of results, we know to add up those results to produce the final result of the `SummedOp`’s evaluation. In theory, this `combo_fn` can be any function over classical complex values, but for convenience we’ve chosen for them to be defined over NumPy arrays and values. This way, large numbers of evaluations, such as after calling `to_matrix` on the list constituents, can be efficiently combined. While the combination function is defined over classical values, it should be understood as the operation by which each Operators’ underlying function is combined to form the underlying Operator function of the `ListOp`. In this way, the `ListOps` are the basis for constructing large and sophisticated Operators, State Functions, and Measurements. + +The base `ListOp` class is particularly interesting, as its `combo_fn` is “the identity list Operation”. Meaning, if we understand the `combo_fn` as a function from a list of complex values to some output, one such function is returning the list as-is. This is powerful for constructing compact hierarchical Operators which return many measurements in multiple dimensional lists. + + + The class `qiskit.opflow.list_ops.list_op.ListOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **oplist** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")*]*) – The list of `OperatorBases` defining this Operator’s underlying function. +* **combo\_fn** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – The recombination function to combine classical results of the `oplist` Operators’ eval functions (e.g. sum). Default is lambda x: x. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient multiplying the operator +* **abelian** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Indicates whether the Operators in `oplist` are known to mutually commute. +* **grad\_combo\_fn** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – The gradient of recombination function. If None, the gradient will be computed automatically. +* **the** (*Note that the default "recombination function" lambda above is essentially*) – +* **values** (*identity - it accepts the list of*) – +* **list.** (*and returns them in a*) – + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### abelian + +Whether the Operators in `oplist` are known to commute with one another. + +**Returns** + +A bool indicating whether the `oplist` is Abelian. + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### coeffs + +Return a list of the coefficients of the operators listed. Raises exception for nested Listops. + + + +### combo\_fn + +The function defining how to combine `oplist` (or Numbers, or NumPy arrays) to produce the Operator’s underlying function. For example, SummedOp’s combination function is to add all of the Operators in `oplist`. + +**Returns** + +The combination function. + + + +### distributive + +Indicates whether the ListOp or subclass is distributive under composition. ListOp and SummedOp are, meaning that (opv @ op) = (opv\[0] @ op + opv\[1] @ op) (using plus for SummedOp, list for ListOp, etc.), while ComposedOp and TensoredOp do not behave this way. + +**Returns** + +A bool indicating whether the ListOp is distributive under composition. + + + +### grad\_combo\_fn + +The gradient of `combo_fn`. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### oplist + +The list of `OperatorBases` defining the underlying function of this Operator. + +**Returns** + +The Operators defining the ListOp + + + +### parameters + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*ListOp*](#qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*ListOp*](#qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### default\_combo\_fn + + + +`static default_combo_fn(x)` + +ListOp default combo function i.e. lambda x: x + +**Return type** + +[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +ListOp’s eval recursively evaluates each Operator in `oplist`, and combines the results using the recombination function `combo_fn`. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function. + +**Returns** + +The output of the `oplist` Operators’ evaluation function, combined with the `combo_fn`. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Raises** + +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – Raised if called for a subclass which is not distributive. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Operators with mixed hierarchies, such as a ListOp containing both PrimitiveOps and ListOps, are not supported. +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – Attempting to call ListOp’s eval from a non-distributive subclass. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### exp\_i + + + +`exp_i()` + +Return an `OperatorBase` equivalent to an exponentiation of self \* -i, e^(-i\*op). + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### log\_i + + + +`log_i(massive=False)` + +Return a `MatrixOp` equivalent to log(H)/-i for this operator H. This function is the effective inverse of exp\_i, equivalent to finding the Hermitian Operator which produces self when exponentiated. For proper ListOps, applies `log_i` to all ops in oplist. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### mul + + + +`mul(scalar)` + +Returns the scalar multiplication of the Operator, overloaded by `*`, including support for Terra’s `Parameters`, which can be bound to values later (via `bind_parameters`). + +**Parameters** + +**scalar** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The real or complex scalar by which to multiply the Operator, or the `ParameterExpression` to serve as a placeholder for a scalar factor. + +**Returns** + +An `OperatorBase` equivalent to product of self and scalar. + +**Return type** + +[*ListOp*](#qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the operator. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j should be permuted to position permutation\[j]. + +**Returns** + +A new ListOp representing the permuted operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### power + + + +`power(exponent)` + +Return Operator composed with self multiple times, overloaded by `**`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensorpower + + + +`tensorpower(other)` + +Return tensor product with self multiple times, overloaded by `^`. + +**Parameters** + +**other** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The int number of times to tensor product self with itself via `tensorpower`. + +**Returns** + +An `OperatorBase` equivalent to the tensorpower of self by other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Returns an equivalent Operator composed of only QuantumCircuit-based primitives, such as `CircuitOp` and `CircuitStateFn`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Returns an equivalent Operator composed of only NumPy-based primitives, such as `MatrixOp` and `VectorStateFn`. + +**Return type** + +[*ListOp*](#qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### to\_pauli\_op + + + +`to_pauli_op(massive=False)` + +Returns an equivalent Operator composed of only Pauli-based primitives, such as `PauliOp`. + +**Return type** + +[*ListOp*](#qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### to\_spmatrix + + + +`to_spmatrix()` + +Returns SciPy sparse matrix representation of the Operator. + +**Returns** + +CSR sparse matrix representation of the Operator, or List thereof. + +**Return type** + +*spmatrix* | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[*spmatrix*] + +### traverse + + + +`traverse(convert_fn, coeff=None)` + +Apply the convert\_fn to each node in the oplist. + +**Parameters** + +* **convert\_fn** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")) – The function to apply to the internal OperatorBase. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *| None*) – A coefficient to multiply by after applying convert\_fn. If it is None, self.coeff is used instead. + +**Returns** + +The converted ListOp. + +**Return type** + +[*ListOp*](#qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.list_ops.SummedOp.md b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.SummedOp.md new file mode 100644 index 00000000000..0fe3009f156 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.SummedOp.md @@ -0,0 +1,253 @@ +--- +title: SummedOp +description: API reference for qiskit.opflow.list_ops.SummedOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.list_ops.SummedOp +--- + +# SummedOp + + + +`qiskit.opflow.list_ops.SummedOp(oplist, coeff=1.0, abelian=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/list_ops/summed_op.py "view source code") + +Bases: [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +Deprecated: A class for lazily representing sums of Operators. Often Operators cannot be efficiently added to one another, but may be manipulated further so that they can be later. This class holds logic to indicate that the Operators in `oplist` are meant to be added together, and therefore if they reach a point in which they can be, such as after evaluation or conversion to matrices, they can be reduced by addition. + + + The class `qiskit.opflow.list_ops.summed_op.SummedOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **oplist** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")*]*) – The Operators being summed. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient multiplying the operator +* **abelian** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Indicates whether the Operators in `oplist` are known to mutually commute. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### abelian + +Whether the Operators in `oplist` are known to commute with one another. + +**Returns** + +A bool indicating whether the `oplist` is Abelian. + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### coeffs + +Return a list of the coefficients of the operators listed. Raises exception for nested Listops. + + + +### combo\_fn + +The function defining how to combine `oplist` (or Numbers, or NumPy arrays) to produce the Operator’s underlying function. For example, SummedOp’s combination function is to add all of the Operators in `oplist`. + +**Returns** + +The combination function. + + + +### distributive + + + +### grad\_combo\_fn + +The gradient of `combo_fn`. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### oplist + +The list of `OperatorBases` defining the underlying function of this Operator. + +**Returns** + +The Operators defining the ListOp + + + +### parameters + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of `self` and `other`, overloaded by `+`. + + + This appends `other` to `self.oplist` without checking `other` is already included or not. If you want to simplify them, please use `simplify()`. + + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +A `SummedOp` equivalent to the sum of self and other. + +**Return type** + +[*SummedOp*](#qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### collapse\_summands + + + +`collapse_summands()` + +Return Operator by simplifying duplicate operators. + +E.g., `SummedOp([2 * X ^ Y, X ^ Y]).collapse_summands() -> SummedOp([3 * X ^ Y])`. + +**Returns** + +A simplified `SummedOp` equivalent to self. + +**Return type** + +[*SummedOp*](#qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### equals + + + +`equals(other)` + +Check if other is equal to self. + + + This is not a mathematical check for equality. If `self` and `other` implement the same operation but differ in the representation (e.g. different type of summands) `equals` will evaluate to `False`. + + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The other operator to check for equality. + +**Returns** + +True, if other and self are equal, otherwise False. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +**Examples** + +```python +>>> from qiskit.opflow import X, Z +>>> 2 * X == X + X +True +>>> X + Z == Z + X +True +``` + +### reduce + + + +`reduce()` + +Try collapsing list or trees of sums. + +Tries to sum up duplicate operators and reduces the operators in the sum. + +**Returns** + +A collapsed version of self, if possible. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_circuit + + + +`to_circuit()` + +Returns the quantum circuit, representing the SummedOp. In the first step, the SummedOp is converted to MatrixOp. This is straightforward for most operators, but it is not supported for operators containing parameterized PrimitiveOps (in that case, OpflowError is raised). In the next step, the MatrixOp representation of SummedOp is converted to circuit. In most cases, if the summands themselves are unitary operators, the SummedOp itself is non-unitary and can not be converted to circuit. In that case, ExtensionError is raised in the underlying modules. + +**Returns** + +The circuit representation of the summed operator. + +**Raises** + +* [**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if SummedOp can not be converted to MatrixOp (e.g. SummedOp is composed of +* **parameterized PrimitiveOps**\*\*)\*\*\*\*.\*\* – + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Returns an equivalent Operator composed of only NumPy-based primitives, such as `MatrixOp` and `VectorStateFn`. + +**Return type** + +[*SummedOp*](#qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### to\_pauli\_op + + + +`to_pauli_op(massive=False)` + +Returns an equivalent Operator composed of only Pauli-based primitives, such as `PauliOp`. + +**Return type** + +[*SummedOp*](#qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.list_ops.TensoredOp.md b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.TensoredOp.md new file mode 100644 index 00000000000..bea4f8dcec2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.TensoredOp.md @@ -0,0 +1,218 @@ +--- +title: TensoredOp +description: API reference for qiskit.opflow.list_ops.TensoredOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.list_ops.TensoredOp +--- + +# TensoredOp + + + +`qiskit.opflow.list_ops.TensoredOp(oplist, coeff=1.0, abelian=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/list_ops/tensored_op.py "view source code") + +Bases: [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +Deprecated: A class for lazily representing tensor products of Operators. Often Operators cannot be efficiently tensored to one another, but may be manipulated further so that they can be later. This class holds logic to indicate that the Operators in `oplist` are meant to be tensored together, and therefore if they reach a point in which they can be, such as after conversion to QuantumCircuits, they can be reduced by tensor product. + + + The class `qiskit.opflow.list_ops.tensored_op.TensoredOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **oplist** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")*]*) – The Operators being tensored. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient multiplying the operator +* **abelian** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Indicates whether the Operators in `oplist` are known to mutually commute. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### abelian + +Whether the Operators in `oplist` are known to commute with one another. + +**Returns** + +A bool indicating whether the `oplist` is Abelian. + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### coeffs + +Return a list of the coefficients of the operators listed. Raises exception for nested Listops. + + + +### combo\_fn + +The function defining how to combine `oplist` (or Numbers, or NumPy arrays) to produce the Operator’s underlying function. For example, SummedOp’s combination function is to add all of the Operators in `oplist`. + +**Returns** + +The combination function. + + + +### distributive + + + +### grad\_combo\_fn + +The gradient of `combo_fn`. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### oplist + +The list of `OperatorBases` defining the underlying function of this Operator. + +**Returns** + +The Operators defining the ListOp + + + +### parameters + + + +### settings + +Return settings. + +## Methods + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +ListOp’s eval recursively evaluates each Operator in `oplist`, and combines the results using the recombination function `combo_fn`. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function. + +**Returns** + +The output of the `oplist` Operators’ evaluation function, combined with the `combo_fn`. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Raises** + +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – Raised if called for a subclass which is not distributive. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Operators with mixed hierarchies, such as a ListOp containing both PrimitiveOps and ListOps, are not supported. +* [**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – Attempting to call ListOp’s eval from a non-distributive subclass. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_circuit + + + +`to_circuit()` + +Returns the quantum circuit, representing the tensored operator. + +**Returns** + +The circuit representation of the tensored operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – for operators where a single underlying circuit can not be produced. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.list_ops.md b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.md new file mode 100644 index 00000000000..2552c2938c8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.list_ops.md @@ -0,0 +1,54 @@ +--- +title: list_ops +description: API reference for qiskit.opflow.list_ops +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.list_ops +--- + + + + + +# qiskit.opflow\.list\_ops + + + +## List Operators + + + +`qiskit.opflow.list_ops` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +List Operators are classes for storing and manipulating lists of Operators, State functions, or Measurements, and include some rule or `combo_fn` defining how the Operator functions of the list constituents should be combined to form to cumulative Operator function of the [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.ListOp"). For example, a [`SummedOp`](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp") has an addition-based `combo_fn`, so once the Operators in its list are evaluated against some bitstring to produce a list of results, we know to add up those results to produce the final result of the [`SummedOp`](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp")’s evaluation. In theory, this `combo_fn` can be any function over classical complex values, but for convenience we’ve chosen for them to be defined over NumPy arrays and values. This way, large numbers of evaluations, such as after calling [`to_matrix()`](qiskit.opflow.list_ops.ListOp#to_matrix "qiskit.opflow.list_ops.ListOp.to_matrix") on the list constituents, can be efficiently combined. While the combination function is defined over classical values, it should be understood as the operation by which each Operators’ underlying function is combined to form the underlying Operator function of the [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.ListOp"). In this way, the [`list_ops`](#module-qiskit.opflow.list_ops "qiskit.opflow.list_ops") are the basis for constructing large and sophisticated Operators, State Functions, and Measurements. + +The base [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.ListOp") class is particularly interesting, as its `combo_fn` is “the identity list Operation”. Meaning, if we understand the `combo_fn` as a function from a list of complex values to some output, one such function is returning the list as-is. This is powerful for constructing compact hierarchical Operators which return many measurements in multiple dimensional lists. For example, if we want to estimate the gradient of some Observable measurement with respect to some parameters in the State function, we can construct separate evaluation Operators for each parameter’s gradient which we must keep track of ourselves in a list, or we can construct a single [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.ListOp") containing the evaluation Operators for each parameter, so the [`eval()`](qiskit.opflow.list_ops.ListOp#eval "qiskit.opflow.list_ops.ListOp.eval") function returns the full gradient vector. Another excellent example of this power is constructing a Quantum kernel matrix: + +```python +data_sfn_list_op = ListOp(data_circuit_state_fns) +qkernel_op_circuits = ~data_sfn_list_op @ data_sfn_list_op +qkernel_sampled = CircuitSampler(backend).convert(qkernel_op_circuits) +qkernel_sampled.eval() +``` + +This will return the two dimensional Quantum kernel matrix, where each element is the inner product of some pair of the data State functions, or in other terms, a measurement of one data [`CircuitStateFn`](qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.CircuitStateFn") by another. + +You’ll encounter the [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.ListOp") subclasses ([`SummedOp`](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp"), [`ComposedOp`](qiskit.opflow.list_ops.ComposedOp "qiskit.opflow.list_ops.ComposedOp"), or [`TensoredOp`](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.TensoredOp")) more often as lazy results of Operator construction operations than as something you need to explicitly construct. Any time we don’t know how to efficiently add, compose, or tensor two [`primitive_ops`](qiskit.opflow.primitive_ops#module-qiskit.opflow.primitive_ops "qiskit.opflow.primitive_ops") or [`state_fns`](qiskit.opflow.state_fns#module-qiskit.opflow.state_fns "qiskit.opflow.state_fns") together, they’re returned in a [`SummedOp`](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp"), [`ComposedOp`](qiskit.opflow.list_ops.ComposedOp "qiskit.opflow.list_ops.ComposedOp"), or [`TensoredOp`](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.TensoredOp"), respectively, so we can still work with their combined function and perhaps convert them into an efficiently combine-able format later. + + + Combination functions do not always behave predictably, and you must understand the conversions you’re making when you working with [`list_ops`](#module-qiskit.opflow.list_ops "qiskit.opflow.list_ops"). Most notably - sampling a sum of two circuits on Quantum hardware does not incorporate interference between the wavefunctions! In this case, we’re sending our State functions through a depolarizing channel before adding them, rather than adding them directly before the measurement. + + +### List Operators + +| | | +| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| [`ListOp`](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.ListOp")(oplist\[, combo\_fn, coeff, abelian, ...]) | Deprecated: A Class for manipulating List Operators, and parent class to `SummedOp`, `ComposedOp` and `TensoredOp`. | +| [`ComposedOp`](qiskit.opflow.list_ops.ComposedOp "qiskit.opflow.list_ops.ComposedOp")(oplist\[, coeff, abelian]) | Deprecated: A class for lazily representing compositions of Operators. | +| [`SummedOp`](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.SummedOp")(oplist\[, coeff, abelian]) | Deprecated: A class for lazily representing sums of Operators. | +| [`TensoredOp`](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.TensoredOp")(oplist\[, coeff, abelian]) | Deprecated: A class for lazily representing tensor products of Operators. | + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.CircuitOp.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.CircuitOp.md new file mode 100644 index 00000000000..749d22e0a5d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.CircuitOp.md @@ -0,0 +1,338 @@ +--- +title: CircuitOp +description: API reference for qiskit.opflow.primitive_ops.CircuitOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.CircuitOp +--- + +# CircuitOp + + + +`qiskit.opflow.primitive_ops.CircuitOp(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/circuit_op.py "view source code") + +Bases: [`PrimitiveOp`](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +Deprecated: Class for Operators backed by Terra’s `QuantumCircuit` module. + + + The class `qiskit.opflow.primitive_ops.circuit_op.CircuitOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The QuantumCircuit which defines the +* **function.** (*behavior of the underlying*) – +* **coeff** – A coefficient multiplying the primitive + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Unsupported primitive, or primitive has ClassicalRegisters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`QuantumCircuit` + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*CircuitOp*](#qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.circuit_op.CircuitOp") + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the circuit. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j of the circuit should be permuted to position permutation\[j]. + +**Returns** + +A new CircuitOp containing the permuted circuit. + +**Return type** + +[*CircuitOp*](#qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.circuit_op.CircuitOp") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*CircuitOp*](#qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.circuit_op.CircuitOp") | [*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_circuit + + + +`to_circuit()` + +Returns a `QuantumCircuit` equivalent to this Operator. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Returns a `CircuitOp` equivalent to this Operator. + +**Return type** + +[*CircuitOp*](#qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.circuit_op.CircuitOp") + +### to\_instruction + + + +`to_instruction()` + +Returns an `Instruction` equivalent to this Operator. + +**Return type** + +[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.MatrixOp.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.MatrixOp.md new file mode 100644 index 00000000000..5d2829aa22b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.MatrixOp.md @@ -0,0 +1,306 @@ +--- +title: MatrixOp +description: API reference for qiskit.opflow.primitive_ops.MatrixOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.MatrixOp +--- + +# MatrixOp + + + +`qiskit.opflow.primitive_ops.MatrixOp(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/matrix_op.py "view source code") + +Bases: [`PrimitiveOp`](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +Deprecated: Class for Operators represented by matrices, backed by Terra’s `Operator` module. + + + The class `qiskit.opflow.primitive_ops.matrix_op.MatrixOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The matrix-like object which defines the behavior of the underlying function. +* **coeff** – A coefficient multiplying the primitive + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – invalid parameters. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – invalid parameters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`Operator` + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*MatrixOp*](#qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.matrix_op.MatrixOp") | [*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*MatrixOp*](#qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.matrix_op.MatrixOp") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### exp\_i + + + +`exp_i()` + +Return a `CircuitOp` equivalent to e^-iH for this operator H + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`permute(permutation=None)` + +Creates a new MatrixOp that acts on the permuted qubits. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – A list defining where each qubit should be permuted. The qubit at index j should be permuted to position permutation\[j]. + +**Returns** + +A new MatrixOp representing the permuted operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*MatrixOp*](#qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.matrix_op.MatrixOp") | [*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_instruction + + + +`to_instruction()` + +Returns an `Instruction` equivalent to this Operator. + +**Return type** + +[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Returns a `MatrixOp` equivalent to this Operator. + +**Return type** + +[*MatrixOp*](#qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.matrix_op.MatrixOp") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliOp.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliOp.md new file mode 100644 index 00000000000..b199d43267a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliOp.md @@ -0,0 +1,337 @@ +--- +title: PauliOp +description: API reference for qiskit.opflow.primitive_ops.PauliOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.PauliOp +--- + +# PauliOp + + + +`qiskit.opflow.primitive_ops.PauliOp(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/pauli_op.py "view source code") + +Bases: [`PrimitiveOp`](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +Deprecated: Class for Operators backed by Terra’s `Pauli` module. + + + The class `qiskit.opflow.primitive_ops.pauli_op.PauliOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The Pauli which defines the behavior of the underlying function. +* **coeff** – A coefficient multiplying the primitive. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – invalid parameters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`Pauli` + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*PauliOp*](#qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### exp\_i + + + +`exp_i()` + +Return a `CircuitOp` equivalent to e^-iH for this operator H. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`permute(permutation)` + +Permutes the sequence of Pauli matrices. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each Pauli should be permuted. The Pauli at index j of the primitive should be permuted to position permutation\[j]. + +**Returns** + +A new PauliOp representing the permuted operator. For operator (X ^ Y ^ Z) and indices=\[1,2,4], it returns (X ^ I ^ Y ^ Z ^ I). + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*PauliOp*](#qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_circuit + + + +`to_circuit()` + +Returns a `QuantumCircuit` equivalent to this Operator. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_instruction + + + +`to_instruction()` + +Returns an `Instruction` equivalent to this Operator. + +**Return type** + +[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_pauli\_op + + + +`to_pauli_op(massive=False)` + +Returns a sum of `PauliOp` s equivalent to this Operator. + +**Return type** + +[*PauliOp*](#qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") + +### to\_spmatrix + + + +`to_spmatrix()` + +Returns SciPy sparse matrix representation of the Operator. + +**Returns** + +CSR sparse matrix representation of the Operator. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – invalid parameters. + +**Return type** + +*spmatrix* + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliSumOp.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliSumOp.md new file mode 100644 index 00000000000..20776cec8f6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PauliSumOp.md @@ -0,0 +1,449 @@ +--- +title: PauliSumOp +description: API reference for qiskit.opflow.primitive_ops.PauliSumOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.PauliSumOp +--- + +# PauliSumOp + + + +`qiskit.opflow.primitive_ops.PauliSumOp(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/pauli_sum_op.py "view source code") + +Bases: [`PrimitiveOp`](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp") + +Deprecated: Class for Operators backed by Terra’s `SparsePauliOp` class. + + + The class `qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The SparsePauliOp which defines the behavior of the underlying function. +* **coeff** – A coefficient multiplying the primitive. +* **grouping\_type** – The type of grouping. If None, the operator is not grouped. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – invalid parameters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### coeffs + +Return the Pauli coefficients. + + + +### grouping\_type + +Type of Grouping + +**Type** + +Returns + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`SparsePauliOp` + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*PauliSumOp*](#qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### exp\_i + + + +`exp_i()` + +Return a `CircuitOp` equivalent to e^-iH for this operator H. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### from\_list + + + +`classmethod from_list(pauli_list, coeff=1.0, dtype=)` + +Construct from a pauli\_list with the form \[(pauli\_str, coeffs)] + +**Parameters** + +* **pauli\_list** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*]]*) – A list of Tuple of pauli\_str and coefficient. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient multiplying the primitive. +* **dtype** ([*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)")) – The dtype to use to construct the internal SparsePauliOp. Defaults to `complex`. + +**Returns** + +The PauliSumOp constructed from the pauli\_list. + +**Return type** + +[*PauliSumOp*](#qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") + +### is\_hermitian + + + +`is_hermitian()` + +Return True if the operator is hermitian. + +Returns: Boolean value + +### is\_zero + + + +`is_zero()` + +Return this operator is zero operator or not. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### matrix\_iter + + + +`matrix_iter(sparse=False)` + +Return a matrix representation iterator. + +This is a lazy iterator that converts each term in the PauliSumOp into a matrix as it is used. To convert to a single matrix use the [`to_matrix()`](#qiskit.opflow.primitive_ops.PauliSumOp.to_matrix "qiskit.opflow.primitive_ops.PauliSumOp.to_matrix") method. + +**Parameters** + +**sparse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – optionally return sparse CSR matrices if True, otherwise return Numpy array matrices (Default: False) + +**Returns** + +matrix iterator object for the PauliSumOp. + +**Return type** + +MatrixIterator + +### mul + + + +`mul(scalar)` + +Returns the scalar multiplication of the Operator, overloaded by `*`, including support for Terra’s `Parameters`, which can be bound to values later (via `bind_parameters`). + +**Parameters** + +**scalar** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The real or complex scalar by which to multiply the Operator, or the `ParameterExpression` to serve as a placeholder for a scalar factor. + +**Returns** + +An `OperatorBase` equivalent to product of self and scalar. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`permute(permutation)` + +Permutes the sequence of `PauliSumOp`. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each Pauli should be permuted. The Pauli at index j of the primitive should be permuted to position permutation\[j]. + +**Returns** + +A new PauliSumOp representing the permuted operator. For operator (X ^ Y ^ Z) and indices=\[1,2,4], it returns (X ^ I ^ Y ^ Z ^ I). + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*PauliSumOp*](#qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce(atol=None, rtol=None)` + +Simplify the primitive `SparsePauliOp`. + +**Parameters** + +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Absolute tolerance for checking if coefficients are zero (Default: 1e-8). +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Relative tolerance for checking if coefficients are zero (Default: 1e-5). + +**Returns** + +The simplified `PauliSumOp`. + +**Return type** + +[*PauliSumOp*](#qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*PauliSumOp*](#qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") | [*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_instruction + + + +`to_instruction()` + +Returns an `Instruction` equivalent to this Operator. + +**Return type** + +[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_pauli\_op + + + +`to_pauli_op(massive=False)` + +Returns a sum of `PauliOp` s equivalent to this Operator. + +**Return type** + +[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.pauli_op.PauliOp") | [*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### to\_spmatrix + + + +`to_spmatrix()` + +Returns SciPy sparse matrix representation of the `PauliSumOp`. + +**Returns** + +CSR sparse matrix representation of the `PauliSumOp`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – invalid parameters. + +**Return type** + +*spmatrix* + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PrimitiveOp.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PrimitiveOp.md new file mode 100644 index 00000000000..65736076e39 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.PrimitiveOp.md @@ -0,0 +1,429 @@ +--- +title: PrimitiveOp +description: API reference for qiskit.opflow.primitive_ops.PrimitiveOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.PrimitiveOp +--- + +# PrimitiveOp + + + +`qiskit.opflow.primitive_ops.PrimitiveOp(primitive, coeff=1.0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/primitive_op.py "view source code") + +Bases: [`OperatorBase`](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +Deprecated: A class for representing basic Operators, backed by Operator primitives from Terra. This class (and inheritors) primarily serves to allow the underlying primitives to “flow” - i.e. interoperability and adherence to the Operator formalism - while the core computational logic mostly remains in the underlying primitives. For example, we would not produce an interface in Terra in which `QuantumCircuit1 + QuantumCircuit2` equaled the Operator sum of the circuit unitaries, rather than simply appending the circuits. However, within the Operator flow summing the unitaries is the expected behavior. + +Note that all mathematical methods are not in-place, meaning that they return a new object, but the underlying primitives are not copied. + + + The class `qiskit.opflow.primitive_ops.primitive_op.PrimitiveOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** ([*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *| spmatrix |*[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") *|*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")) – The operator primitive being wrapped. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient multiplying the primitive. + +**Return type** + +[PrimitiveOp](#qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.PrimitiveOp") + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Return Operator Composition between self and other (linear algebra-style: A\@B(x) = A(B(x))), overloaded by `@`. + +Note: You must be conscious of Quantum Circuit vs. Linear Algebra ordering conventions. Meaning, X.compose(Y) produces an X∘Y on qubit 0, but would produce a QuantumCircuit which looks like + +> -\[Y]-\[X]- + +Because Terra prints circuits with the initial state at the left side of the circuit. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` with which to compose self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An `OperatorBase` equivalent to the function composition of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### exp\_i + + + +`exp_i()` + +Return Operator exponentiation, equaling e^(-i \* op) + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### log\_i + + + +`log_i(massive=False)` + +Return a `MatrixOp` equivalent to log(H)/-i for this operator H. This function is the effective inverse of exp\_i, equivalent to finding the Hermitian Operator which produces self when exponentiated. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### mul + + + +`mul(scalar)` + +Returns the scalar multiplication of the Operator, overloaded by `*`, including support for Terra’s `Parameters`, which can be bound to values later (via `bind_parameters`). + +**Parameters** + +**scalar** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The real or complex scalar by which to multiply the Operator, or the `ParameterExpression` to serve as a placeholder for a scalar factor. + +**Returns** + +An `OperatorBase` equivalent to product of self and scalar. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`permute(permutation)` + +Permutes the qubits of the operator. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j should be permuted to position permutation\[j]. + +**Returns** + +A new OperatorBase containing the permuted operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – if indices do not define a new index for each qubit. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, X.tensor(Y) produces an X on qubit 0 and an Y on qubit 1, or X⨂Y, but would produce a QuantumCircuit which looks like + +> -\[Y]- -\[X]- + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensorpower + + + +`tensorpower(other)` + +Return tensor product with self multiple times, overloaded by `^`. + +**Parameters** + +**other** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The int number of times to tensor product self with itself via `tensorpower`. + +**Returns** + +An `OperatorBase` equivalent to the tensorpower of self by other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### to\_circuit + + + +`to_circuit()` + +Returns a `QuantumCircuit` equivalent to this Operator. + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Returns a `CircuitOp` equivalent to this Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_instruction + + + +`to_instruction()` + +Returns an `Instruction` equivalent to this Operator. + +**Return type** + +[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Returns a `MatrixOp` equivalent to this Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_pauli\_op + + + +`to_pauli_op(massive=False)` + +Returns a sum of `PauliOp` s equivalent to this Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.TaperedPauliSumOp.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.TaperedPauliSumOp.md new file mode 100644 index 00000000000..ab1b0c6ac54 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.TaperedPauliSumOp.md @@ -0,0 +1,130 @@ +--- +title: TaperedPauliSumOp +description: API reference for qiskit.opflow.primitive_ops.TaperedPauliSumOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.TaperedPauliSumOp +--- + +# TaperedPauliSumOp + + + +`qiskit.opflow.primitive_ops.TaperedPauliSumOp(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/tapered_pauli_sum_op.py "view source code") + +Bases: [`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp") + +Deprecated: Class for PauliSumOp after tapering + + + The class `qiskit.opflow.primitive_ops.tapered_pauli_sum_op.TaperedPauliSumOp` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The SparsePauliOp which defines the behavior of the underlying function. +* **z2\_symmetries** – Z2 symmetries which the Operator has. +* **coeff** – A coefficient multiplying the primitive. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – invalid parameters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +The scalar coefficient multiplying the Operator. + +**Returns** + +The coefficient. + + + +### coeffs + +Return the Pauli coefficients. + + + +### grouping\_type + +Type of Grouping + +**Type** + +Returns + + + +### instance\_id + +Return the unique instance id. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`SparsePauliOp` + +The primitive defining the underlying function of the Operator. + +**Returns** + +The primitive object. + + + +### settings + +Return operator settings. + + + +### z2\_symmetries + +Z2 symmetries which the Operator has. + +**Returns** + +The Z2 Symmetries. + +## Methods + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.Z2Symmetries.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.Z2Symmetries.md new file mode 100644 index 00000000000..6584875379a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.Z2Symmetries.md @@ -0,0 +1,220 @@ +--- +title: Z2Symmetries +description: API reference for qiskit.opflow.primitive_ops.Z2Symmetries +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.primitive_ops.Z2Symmetries +--- + +# Z2Symmetries + + + +`qiskit.opflow.primitive_ops.Z2Symmetries(symmetries, sq_paulis, sq_list, tapering_values=None, tol=1e-14)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/primitive_ops/tapered_pauli_sum_op.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: Z2 Symmetries + + + The class `qiskit.opflow.primitive_ops.tapered_pauli_sum_op.Z2Symmetries` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **symmetries** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli")*]*) – the list of Pauli objects representing the Z\_2 symmetries +* **sq\_paulis** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli")*]*) – the list of single - qubit Pauli objects to construct the Clifford operators +* **sq\_list** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – the list of support of the single-qubit Pauli objects used to build the Clifford operators +* **tapering\_values** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – values determines the sector. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Tolerance threshold for ignoring real and complex parts of a coefficient. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – Invalid paulis + +## Attributes + + + +### cliffords + +Get clifford operators, build based on symmetries and single-qubit X. :returns: a list of unitaries used to diagonalize the Hamiltonian. + + + +### settings + +Return operator settings. + + + +### sq\_list + +returns sq list + + + +### sq\_paulis + +returns sq paulis + + + +### symmetries + +return symmetries + + + +### tapering\_values + +returns tapering values + + + +### tol + +Tolerance threshold for ignoring real and complex parts of a coefficient. + +## Methods + +### consistent\_tapering + + + +`consistent_tapering(operator)` + +Tapering the operator with the same manner of how this tapered operator is created. i.e., using the same Cliffords and tapering values. + +**Parameters** + +**operator** ([*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp")) – the to-be-tapered operator + +**Returns** + +The tapered operator + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – The given operator does not commute with the symmetry + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### convert\_clifford + + + +`convert_clifford(operator)` + +This method operates the first part of the tapering. It converts the operator by composing it with the clifford unitaries defined in the current symmetry. + +**Parameters** + +**operator** ([*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp")) – to-be-tapered operator + +**Returns** + +[`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") corresponding to the converted operator. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – Z2 symmetries, single qubit pauli and single qubit list cannot be empty + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### copy + + + +`copy()` + +Get a copy of self. :returns: copy + +**Return type** + +[*Z2Symmetries*](#qiskit.opflow.primitive_ops.Z2Symmetries "qiskit.opflow.primitive_ops.tapered_pauli_sum_op.Z2Symmetries") + +### find\_Z2\_symmetries + + + +`classmethod find_Z2_symmetries(operator)` + +Finds Z2 Pauli-type symmetries of an Operator. + +**Returns** + +a z2\_symmetries object contains symmetries, single-qubit X, single-qubit list. + +**Return type** + +[*Z2Symmetries*](#qiskit.opflow.primitive_ops.Z2Symmetries "qiskit.opflow.primitive_ops.tapered_pauli_sum_op.Z2Symmetries") + +### is\_empty + + + +`is_empty()` + +Check the z2\_symmetries is empty or not. :returns: Empty or not + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### taper + + + +`taper(operator)` + +Taper an operator based on the z2\_symmetries info and sector defined by tapering\_values. The tapering\_values will be stored into the resulted operator for a record. + +The tapering is a two-step algorithm which first converts the operator into a [`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") with same eigenvalues but where some qubits are only acted upon with the Pauli operators I or X. The number M of these redundant qubits is equal to the number M of identified symmetries. + +The second step of the reduction consists in replacing these qubits with the possible eigenvalues of the corresponding Pauli X, giving 2^M new operators with M less qubits. If an eigenvalue sector was previously identified for the solution, then this reduces to 1 new operator with M less qubits. + +**Parameters** + +**operator** ([*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp")) – the to-be-tapered operator + +**Returns** + +\[[`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")]; otherwise, [`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") + +**Return type** + +If tapering\_values is None + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – Z2 symmetries, single qubit pauli and single qubit list cannot be empty + +### taper\_clifford + + + +`taper_clifford(operator)` + +This method operates the second part of the tapering. This function assumes that the input operators have already been transformed using [`convert_clifford()`](#qiskit.opflow.primitive_ops.Z2Symmetries.convert_clifford "qiskit.opflow.primitive_ops.Z2Symmetries.convert_clifford"). The redundant qubits due to the symmetries are dropped and replaced by their two possible eigenvalues. The tapering\_values will be stored into the resulted operator for a record. + +**Parameters** + +**operator** ([*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.pauli_sum_op.PauliSumOp")) – Partially tapered operator resulting from a call to [`convert_clifford()`](#qiskit.opflow.primitive_ops.Z2Symmetries.convert_clifford "qiskit.opflow.primitive_ops.Z2Symmetries.convert_clifford") + +**Returns** + +\[[`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")]; otherwise, [`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") + +**Return type** + +If tapering\_values is None + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – Z2 symmetries, single qubit pauli and single qubit list cannot be empty + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.md b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.md new file mode 100644 index 00000000000..56d01731352 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.primitive_ops.md @@ -0,0 +1,51 @@ +--- +title: primitive_ops +description: API reference for qiskit.opflow.primitive_ops +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.primitive_ops +--- + + + + + +# qiskit.opflow\.primitive\_ops + + + +## Primitive Operators + + + +`qiskit.opflow.primitive_ops` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +Operators are defined to be functions which take State functions to State functions. + +PrimitiveOps are the classes for representing basic Operators, backed by computational Operator primitives from Terra. These classes (and inheritors) primarily serve to allow the underlying primitives to “flow” - i.e. interoperability and adherence to the Operator formalism - while the core computational logic mostly remains in the underlying primitives. For example, we would not produce an interface in Terra in which `QuantumCircuit1 + QuantumCircuit2` equaled the Operator sum of the circuit unitaries, rather than simply appending the circuits. However, within the Operator flow summing the unitaries is the expected behavior. + + + All mathematical methods are not in-place, meaning that they return a new object, but the underlying primitives are not copied. + + +### Primitive Operators + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| [`PrimitiveOp`](qiskit.opflow.primitive_ops.PrimitiveOp "qiskit.opflow.primitive_ops.PrimitiveOp")(primitive\[, coeff]) | Deprecated: A class for representing basic Operators, backed by Operator primitives from Terra. | +| [`CircuitOp`](qiskit.opflow.primitive_ops.CircuitOp "qiskit.opflow.primitive_ops.CircuitOp")(\*args, \*\*kwargs) | Deprecated: Class for Operators backed by Terra's `QuantumCircuit` module. | +| [`MatrixOp`](qiskit.opflow.primitive_ops.MatrixOp "qiskit.opflow.primitive_ops.MatrixOp")(\*args, \*\*kwargs) | Deprecated: Class for Operators represented by matrices, backed by Terra's `Operator` module. | +| [`PauliOp`](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.PauliOp")(\*args, \*\*kwargs) | Deprecated: Class for Operators backed by Terra's `Pauli` module. | +| [`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp")(\*args, \*\*kwargs) | Deprecated: Class for Operators backed by Terra's `SparsePauliOp` class. | +| [`TaperedPauliSumOp`](qiskit.opflow.primitive_ops.TaperedPauliSumOp "qiskit.opflow.primitive_ops.TaperedPauliSumOp")(\*args, \*\*kwargs) | Deprecated: Class for PauliSumOp after tapering | + +### Symmetries + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +| [`Z2Symmetries`](qiskit.opflow.primitive_ops.Z2Symmetries "qiskit.opflow.primitive_ops.Z2Symmetries")(symmetries, sq\_paulis, sq\_list) | Deprecated: Z2 Symmetries | + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.CVaRMeasurement.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.CVaRMeasurement.md new file mode 100644 index 00000000000..cec5387bd2d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.CVaRMeasurement.md @@ -0,0 +1,352 @@ +--- +title: CVaRMeasurement +description: API reference for qiskit.opflow.state_fns.CVaRMeasurement +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.CVaRMeasurement +--- + +# CVaRMeasurement + + + +`qiskit.opflow.state_fns.CVaRMeasurement(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/cvar_measurement.py "view source code") + +Bases: [`OperatorStateFn`](qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") + +**Deprecated: A specialized measurement class to compute CVaR expectation values.** + +See [https://arxiv.org/pdf/1907.04769.pdf](https://arxiv.org/pdf/1907.04769.pdf) for further details. + +Used in `CVaRExpectation`, see there for more details. + + + The class `qiskit.opflow.state_fns.cvar_measurement.CVaRMeasurement` is deprecated as of qiskit 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The `OperatorBase` which defines the diagonal operator measurement. +* **coeff** – A coefficient by which to multiply the state function +* **alpha** – A real-valued parameter between 0 and 1 which specifies the fraction of observed samples to include when computing the objective value. alpha = 1 corresponds to a standard observable expectation value. alpha = 0 corresponds to only using the single sample with the lowest energy. alpha = 0.5 corresponds to ranking each observation by lowest energy and using the best + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – TODO remove that this raises an error +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If alpha is not in \[0, 1]. +* [**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – If the primitive is not diagonal. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### alpha + +**A real-valued parameter between 0 and 1 which specifies the** + +fraction of observed samples to include when computing the objective value. alpha = 1 corresponds to a standard observable expectation value. alpha = 0 corresponds to only using the single sample with the lowest energy. alpha = 0.5 corresponds to ranking each observation by lowest energy and using the best half. + +**Returns** + +The parameter alpha which was given at initialization + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`OperatorBase` + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### adjoint + + + +`adjoint()` + +The adjoint of a CVaRMeasurement is not defined. + +**Returns** + +Does not return anything, raises an error. + +**Raises** + +[**OpflowError**](opflow#qiskit.opflow.OpflowError "qiskit.opflow.OpflowError") – The adjoint of a CVaRMeasurement is not defined. + +### compute\_cvar + + + +`compute_cvar(energies, probabilities)` + +Given the energies of each sampled measurement outcome (H\_i) as well as the sampling probability of each measurement outcome (p\_i, we can compute the CVaR. Note that the sampling probabilities serve as an alternative to knowing the counts of each observation and that the input energies are assumed to be sorted in increasing order. + +Consider the outcome with index j, such that only some of the samples with measurement outcome j will be used in computing CVaR. The CVaR calculation can then be separated into two parts. First we sum each of the energies for outcomes i \< j, weighted by the probability of observing that outcome (i.e the normalized counts). Second, we add the energy for outcome j, weighted by the difference (α - sum\_i\ + +`eval(front=None)` + +Given the energies of each sampled measurement outcome (H\_i) as well as the sampling probability of each measurement outcome (p\_i, we can compute the CVaR as H\_j + 1/α\*(sum\_i\ + +`eval_variance(front=None)` + +Given the energies of each sampled measurement outcome (H\_i) as well as the sampling probability of each measurement outcome (p\_i, we can compute the variance of the CVaR estimator as H\_j^2 + 1/α \* (sum\_i\], where H is the diagonal observable and bi corresponds to measurement outcome i. Given this, E\[X^2] = E\[\^2] + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *| None*) – A StateFn or primitive which specifies the results of evaluating a quantum state. + +**Returns** + +**The Var\[CVaR] of the diagonal observable specified by self.primitive** + +and the sampled quantum state described by the inputs (energies, probabilities). For index j (described above), the CVaR is computed as H\_j^2 + 1/α\*(sum\_i\ + +`get_outcome_energies_probabilities(front=None)` + +In order to compute the CVaR of an observable expectation, we require the energies of each sampled measurement outcome as well as the sampling probability of each measurement outcome. Note that the counts for each measurement outcome will also suffice (and this is often how the CVaR is presented). + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – A StateFn or a primitive which defines a StateFn. This input holds the results of a sampled/simulated circuit. + +**Returns** + +**Two lists of equal length. energies contains the energy of each** + +unique measurement outcome computed against the diagonal observable stored in self.primitive. probabilities contains the corresponding sampling probability for each measurement outcome in energies. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – front isn’t a DictStateFn or VectorStateFn + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)"), [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")] + +### mul + + + +`mul(scalar)` + +Returns the scalar multiplication of the Operator, overloaded by `*`, including support for Terra’s `Parameters`, which can be bound to values later (via `bind_parameters`). + +**Parameters** + +**scalar** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The real or complex scalar by which to multiply the Operator, or the `ParameterExpression` to serve as a placeholder for a scalar factor. + +**Returns** + +An `OperatorBase` equivalent to product of self and scalar. + +**Return type** + +[*CVaRMeasurement*](#qiskit.opflow.state_fns.CVaRMeasurement "qiskit.opflow.state_fns.cvar_measurement.CVaRMeasurement") + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of samples to take to approximate the State function. +* **massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. +* **reverse\_endianness** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reverse the endianness of the bitstrings in the return dict to match Terra’s big-endianness. + +**Returns** + +A dict containing pairs sampled strings from the State function and sampling frequency divided by shots. + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, Plus.tensor(Zero) produces a |+⟩ on qubit 0 and a |0⟩ on qubit 1, or |+⟩⨂|0⟩, but would produce a QuantumCircuit like + +> |0⟩– |+⟩– + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorStateFn*](qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") | [*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Not defined. + +### to\_density\_matrix + + + +`to_density_matrix(massive=False)` + +Not defined. + +### to\_matrix + + + +`to_matrix(massive=False)` + +Not defined. + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Not defined. + +### traverse + + + +`traverse(convert_fn, coeff=None)` + +Apply the convert\_fn to the internal primitive if the primitive is an Operator (as in the case of `OperatorStateFn`). Otherwise do nothing. Used by converters. + +**Parameters** + +* **convert\_fn** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")) – The function to apply to the internal OperatorBase. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *| None*) – A coefficient to multiply by after applying convert\_fn. If it is None, self.coeff is used instead. + +**Returns** + +The converted StateFn. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.CircuitStateFn.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.CircuitStateFn.md new file mode 100644 index 00000000000..79358a9611d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.CircuitStateFn.md @@ -0,0 +1,375 @@ +--- +title: CircuitStateFn +description: API reference for qiskit.opflow.state_fns.CircuitStateFn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.CircuitStateFn +--- + +# CircuitStateFn + + + +`qiskit.opflow.state_fns.CircuitStateFn(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/circuit_state_fn.py "view source code") + +Bases: [`StateFn`](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +Deprecated: A class for state functions and measurements which are defined by the action of a QuantumCircuit starting from |0⟩, and stored using Terra’s `QuantumCircuit` class. + + + The class `qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The `QuantumCircuit` (or `Instruction`, which will be converted) which defines the behavior of the underlying function. +* **coeff** – A coefficient multiplying the state function. +* **is\_measurement** – Whether the StateFn is a measurement operator. +* **from\_operator** – if True the StateFn is derived from OperatorStateFn. (Default: False) + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Unsupported primitive, or primitive has ClassicalRegisters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`QuantumCircuit` + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") | [*ListOp*](qiskit.opflow.list_ops.ListOp "qiskit.opflow.list_ops.list_op.ListOp") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Composition (Linear algebra-style: A\@B(x) = A(B(x))) is not well defined for states in the binary function model, but is well defined for measurements. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to compose with self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An Operator equivalent to the function composition of self and other. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If self is not a measurement, it cannot be composed from the right. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### from\_dict + + + +`static from_dict(density_dict)` + +Construct the CircuitStateFn from a dict mapping strings to probability densities. + +**Parameters** + +**density\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dict representing the desired state. + +**Returns** + +The CircuitStateFn created from the dict. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") + +### from\_vector + + + +`static from_vector(statevector)` + +Construct the CircuitStateFn from a vector representing the statevector. + +**Parameters** + +**statevector** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – The statevector representing the desired state. + +**Returns** + +The CircuitStateFn created from the vector. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the circuit. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j of the circuit should be permuted to position permutation\[j]. + +**Returns** + +A new CircuitStateFn containing the permuted circuit. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, Plus.tensor(Zero) produces a |+⟩ on qubit 0 and a |0⟩ on qubit 1, or |+⟩⨂|0⟩, but would produce a QuantumCircuit like: + +> |0⟩– |+⟩– + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*CircuitStateFn*](#qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.circuit_state_fn.CircuitStateFn") | [*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_circuit + + + +`to_circuit(meas=False)` + +Return QuantumCircuit representing StateFn + +**Return type** + +[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Return `StateFnCircuit` corresponding to this StateFn. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_density\_matrix + + + +`to_density_matrix(massive=False)` + +Return numpy matrix of density operator, warn if more than 16 qubits to force the user to set massive=True if they want such a large matrix. Generally big methods like this should require the use of a converter, but in this case a convenience method for quick hacking and access to classical tools is appropriate. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_instruction + + + +`to_instruction()` + +Return Instruction corresponding to primitive. + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.DictStateFn.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.DictStateFn.md new file mode 100644 index 00000000000..b147143c283 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.DictStateFn.md @@ -0,0 +1,307 @@ +--- +title: DictStateFn +description: API reference for qiskit.opflow.state_fns.DictStateFn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.DictStateFn +--- + +# DictStateFn + + + +`qiskit.opflow.state_fns.DictStateFn(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/dict_state_fn.py "view source code") + +Bases: [`StateFn`](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +Deprecated: A class for state functions and measurements which are defined by a lookup table, stored in a dict. + + + The class `qiskit.opflow.state_fns.dict_state_fn.DictStateFn` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The dict, single bitstring (if defining a basis sate), or Qiskit Result, which defines the behavior of the underlying function. +* **coeff** – A coefficient by which to multiply the state function. +* **is\_measurement** – Whether the StateFn is a measurement operator. +* **from\_operator** – if True the StateFn is derived from OperatorStateFn. (Default: False) + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – invalid parameters. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`Dict[str, complex]` + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*DictStateFn*](#qiskit.opflow.state_fns.DictStateFn "qiskit.opflow.state_fns.dict_state_fn.DictStateFn") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the state function. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j of the circuit should be permuted to position permutation\[j]. + +**Returns** + +A new StateFn containing the permuted primitive. + +**Return type** + +[*DictStateFn*](#qiskit.opflow.state_fns.DictStateFn "qiskit.opflow.state_fns.dict_state_fn.DictStateFn") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of samples to take to approximate the State function. +* **massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. +* **reverse\_endianness** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reverse the endianness of the bitstrings in the return dict to match Terra’s big-endianness. + +**Returns** + +A dict containing pairs sampled strings from the State function and sampling frequency divided by shots. + +**Return type** + +[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, Plus.tensor(Zero) produces a |+⟩ on qubit 0 and a |0⟩ on qubit 1, or |+⟩⨂|0⟩, but would produce a QuantumCircuit like + +> |0⟩– |+⟩– + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Convert this state function to a `CircuitStateFn`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_density\_matrix + + + +`to_density_matrix(massive=False)` + +Return matrix representing product of StateFn evaluated on pairs of basis states. Overridden by child classes. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +The NumPy array representing the density matrix of the State function. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If massive is set to False, and exponentially large computation is needed. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_spmatrix + + + +`to_spmatrix()` + +Same as to\_matrix, but returns csr sparse matrix. + +**Returns** + +CSR sparse matrix representation of the State function. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – invalid parameters. + +**Return type** + +*spmatrix* + +### to\_spmatrix\_op + + + +`to_spmatrix_op()` + +Convert this state function to a `SparseVectorStateFn`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.OperatorStateFn.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.OperatorStateFn.md new file mode 100644 index 00000000000..081f30b6006 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.OperatorStateFn.md @@ -0,0 +1,272 @@ +--- +title: OperatorStateFn +description: API reference for qiskit.opflow.state_fns.OperatorStateFn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.OperatorStateFn +--- + +# OperatorStateFn + + + +`qiskit.opflow.state_fns.OperatorStateFn(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/operator_state_fn.py "view source code") + +Bases: [`StateFn`](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +Deprecated: A class for state functions and measurements which are defined by a density Operator, stored using an `OperatorBase`. + + + The class `qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The `OperatorBase` which defines the behavior of the underlying State function. +* **coeff** – A coefficient by which to multiply the state function +* **is\_measurement** – Whether the StateFn is a measurement operator + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`OperatorBase` + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorStateFn*](#qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") | [*SummedOp*](qiskit.opflow.list_ops.SummedOp "qiskit.opflow.list_ops.summed_op.SummedOp") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*OperatorStateFn*](#qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the state function. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j of the circuit should be permuted to position permutation\[j]. + +**Returns** + +A new StateFn containing the permuted primitive. + +**Return type** + +[*OperatorStateFn*](#qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of samples to take to approximate the State function. +* **massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. +* **reverse\_endianness** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reverse the endianness of the bitstrings in the return dict to match Terra’s big-endianness. + +**Returns** + +A dict containing pairs sampled strings from the State function and sampling frequency divided by shots. + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, Plus.tensor(Zero) produces a |+⟩ on qubit 0 and a |0⟩ on qubit 1, or |+⟩⨂|0⟩, but would produce a QuantumCircuit like + +> |0⟩– |+⟩– + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorStateFn*](#qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") | [*TensoredOp*](qiskit.opflow.list_ops.TensoredOp "qiskit.opflow.list_ops.tensored_op.TensoredOp") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Return `StateFnCircuit` corresponding to this StateFn. Ignore for now because this is undefined. TODO maybe call to\_pauli\_op and diagonalize here, but that could be very inefficient, e.g. splitting one Stabilizer measurement into hundreds of 1 qubit Paulis. + +### to\_density\_matrix + + + +`to_density_matrix(massive=False)` + +Return numpy matrix of density operator, warn if more than 16 qubits to force the user to set massive=True if they want such a large matrix. Generally big methods like this should require the use of a converter, but in this case a convenience method for quick hacking and access to classical tools is appropriate. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Note: this does not return a density matrix, it returns a classical matrix containing the quantum or classical vector representing the evaluation of the state function on each binary basis state. Do not assume this is is a normalized quantum or classical probability vector. If we allowed this to return a density matrix, then we would need to change the definition of composition to be \~Op @ StateFn @ Op for those cases, whereas by this methodology we can ensure that composition always means Op @ StateFn. + +Return numpy vector of state vector, warn if more than 16 qubits to force the user to set massive=True if they want such a large vector. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +Vector of state vector + +**Return type** + +np.ndarray + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid parameters. + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Return a MatrixOp for this operator. + +**Return type** + +[*OperatorStateFn*](#qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.operator_state_fn.OperatorStateFn") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.SparseVectorStateFn.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.SparseVectorStateFn.md new file mode 100644 index 00000000000..66570accf44 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.SparseVectorStateFn.md @@ -0,0 +1,281 @@ +--- +title: SparseVectorStateFn +description: API reference for qiskit.opflow.state_fns.SparseVectorStateFn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.SparseVectorStateFn +--- + +# SparseVectorStateFn + + + +`qiskit.opflow.state_fns.SparseVectorStateFn(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/sparse_vector_state_fn.py "view source code") + +Bases: [`StateFn`](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +Deprecated: A class for sparse state functions and measurements in vector representation. + +This class uses `scipy.sparse.spmatrix` for the internal representation. + + + The class `qiskit.opflow.state_fns.sparse_vector_state_fn.SparseVectorStateFn` is deprecated as of qiskit 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The underlying sparse vector. +* **coeff** – A coefficient multiplying the state function. +* **is\_measurement** – Whether the StateFn is a measurement operator + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the primitive is not a column vector. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the number of elements in the primitive is not a power of 2. + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`spmatrix` + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*SparseVectorStateFn*](#qiskit.opflow.state_fns.SparseVectorStateFn "qiskit.opflow.state_fns.sparse_vector_state_fn.SparseVectorStateFn") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of samples to take to approximate the State function. +* **massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. +* **reverse\_endianness** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reverse the endianness of the bitstrings in the return dict to match Terra’s big-endianness. + +**Returns** + +A dict containing pairs sampled strings from the State function and sampling frequency divided by shots. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Convert this state function to a `CircuitStateFn`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_dict\_fn + + + +`to_dict_fn()` + +Convert this state function to a `DictStateFn`. + +**Returns** + +A new DictStateFn equivalent to `self`. + +**Return type** + +[*StateFn*](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Return a `VectorStateFn` for this `StateFn`. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +A VectorStateFn equivalent to self. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_spmatrix + + + +`to_spmatrix()` + +Return SciPy sparse matrix representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. + +**Returns** + +The SciPy `spmatrix` equivalent to this Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.StateFn.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.StateFn.md new file mode 100644 index 00000000000..f16bc314acd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.StateFn.md @@ -0,0 +1,461 @@ +--- +title: StateFn +description: API reference for qiskit.opflow.state_fns.StateFn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.StateFn +--- + +# StateFn + + + +`qiskit.opflow.state_fns.StateFn(primitive=None, coeff=1.0, is_measurement=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/state_fn.py "view source code") + +Bases: [`OperatorBase`](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +Deprecated: A class for representing state functions and measurements. + +State functions are defined to be complex functions over a single binary string (as compared to an operator, which is defined as a function over two binary strings, or a function taking a binary function to another binary function). This function may be called by the eval() method. + +Measurements are defined to be functionals over StateFns, taking them to real values. Generally, this real value is interpreted to represent the probability of some classical state (binary string) being observed from a probabilistic or quantum system represented by a StateFn. This leads to the equivalent definition, which is that a measurement m is a function over binary strings producing StateFns, such that the probability of measuring a given binary string b from a system with StateFn f is equal to the inner product between f and m(b). + +NOTE: State functions here are not restricted to wave functions, as there is no requirement of normalization. + + + The class `qiskit.opflow.state_fns.state_fn.StateFn` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*Result*](qiskit.result.Result "qiskit.result.result.Result") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The primitive which defines the behavior of the underlying State function. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A coefficient by which the state function is multiplied. +* **is\_measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the StateFn is a measurement operator + +**Return type** + +[StateFn](#qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.StateFn") + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### assign\_parameters + + + +`assign_parameters(param_dict)` + +Binds scalar values to any Terra `Parameters` in the coefficients or primitives of the Operator, or substitutes one `Parameter` for another. This method differs from Terra’s `assign_parameters` in that it also supports lists of values to assign for a give `Parameter`, in which case self will be copied for each parameterization in the binding list(s), and all the copies will be returned in an `OpList`. If lists of parameterizations are used, every `Parameter` in the param\_dict must have the same length list of parameterizations. + +**Parameters** + +**param\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of `Parameters` to replace, and values or lists of values by which to replace them. + +**Returns** + +The `OperatorBase` with the `Parameters` in self replaced by the values or `Parameters` in param\_dict. If param\_dict contains parameterization lists, this `OperatorBase` is an `OpList`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### compose + + + +`compose(other, permutation=None, front=False)` + +Composition (Linear algebra-style: A\@B(x) = A(B(x))) is not well defined for states in the binary function model, but is well defined for measurements. + +**Parameters** + +* **other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The Operator to compose with self. +* **permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – `List[int]` which defines permutation on other operator. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If front==True, return `other.compose(self)`. + +**Returns** + +An Operator equivalent to the function composition of self and other. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If self is not a measurement, it cannot be composed from the right. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### equals + + + +`equals(other)` + +Evaluate Equality between Operators, overloaded by `==`. Only returns True if self and other are of the same representation (e.g. a DictStateFn and CircuitStateFn will never be equal, even if their vector representations are equal), their underlying primitives are equal (this means for ListOps, OperatorStateFns, or EvolvedOps the equality is evaluated recursively downwards), and their coefficients are equal. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to compare to self. + +**Returns** + +A bool equal to the equality of self and other. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### mul + + + +`mul(scalar)` + +Returns the scalar multiplication of the Operator, overloaded by `*`, including support for Terra’s `Parameters`, which can be bound to values later (via `bind_parameters`). + +**Parameters** + +**scalar** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The real or complex scalar by which to multiply the Operator, or the `ParameterExpression` to serve as a placeholder for a scalar factor. + +**Returns** + +An `OperatorBase` equivalent to product of self and scalar. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the state function. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j of the circuit should be permuted to position permutation\[j]. + +**Returns** + +A new StateFn containing the permuted primitive. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### power + + + +`power(exponent)` + +Compose with Self Multiple Times, undefined for StateFns. + +**Parameters** + +**exponent** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to compose self with self. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – This function is not defined for StateFns. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### reduce + + + +`reduce()` + +Try collapsing the Operator structure, usually after some type of conversion, e.g. trying to add Operators in a SummedOp or delete needless IGates in a CircuitOp. If no reduction is available, just returns self. + +**Returns** + +The reduced `OperatorBase`. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of samples to take to approximate the State function. +* **massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. +* **reverse\_endianness** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reverse the endianness of the bitstrings in the return dict to match Terra’s big-endianness. + +**Returns** + +A dict containing pairs sampled strings from the State function and sampling frequency divided by shots. + +**Return type** + +[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, Plus.tensor(Zero) produces a |+⟩ on qubit 0 and a |0⟩ on qubit 1, or |+⟩⨂|0⟩, but would produce a QuantumCircuit like + +> |0⟩– |+⟩– + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### tensorpower + + + +`tensorpower(other)` + +Return tensor product with self multiple times, overloaded by `^`. + +**Parameters** + +**other** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The int number of times to tensor product self with itself via `tensorpower`. + +**Returns** + +An `OperatorBase` equivalent to the tensorpower of self by other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Returns a `CircuitOp` equivalent to this Operator. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_density\_matrix + + + +`to_density_matrix(massive=False)` + +Return matrix representing product of StateFn evaluated on pairs of basis states. Overridden by child classes. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +The NumPy array representing the density matrix of the State function. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If massive is set to False, and exponentially large computation is needed. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Return a `VectorStateFn` for this `StateFn`. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +A VectorStateFn equivalent to self. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### traverse + + + +`traverse(convert_fn, coeff=None)` + +Apply the convert\_fn to the internal primitive if the primitive is an Operator (as in the case of `OperatorStateFn`). Otherwise do nothing. Used by converters. + +**Parameters** + +* **convert\_fn** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")) – The function to apply to the internal OperatorBase. +* **coeff** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *| None*) – A coefficient to multiply by after applying convert\_fn. If it is None, self.coeff is used instead. + +**Returns** + +The converted StateFn. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.VectorStateFn.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.VectorStateFn.md new file mode 100644 index 00000000000..c34f2bce9be --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.VectorStateFn.md @@ -0,0 +1,306 @@ +--- +title: VectorStateFn +description: API reference for qiskit.opflow.state_fns.VectorStateFn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.opflow.state_fns.VectorStateFn +--- + +# VectorStateFn + + + +`qiskit.opflow.state_fns.VectorStateFn(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/opflow/state_fns/vector_state_fn.py "view source code") + +Bases: [`StateFn`](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +Deprecated: A class for state functions and measurements which are defined in vector representation, and stored using Terra’s `Statevector` class. + + + The class `qiskit.opflow.state_fns.vector_state_fn.VectorStateFn` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +**Parameters** + +* **primitive** – The `Statevector`, NumPy array, or list, which defines the behavior of the underlying function. +* **coeff** – A coefficient multiplying the state function. +* **is\_measurement** – Whether the StateFn is a measurement operator + +## Attributes + + + +### INDENTATION + +`= '  '` + + + +### coeff + +A coefficient by which the state function is multiplied. + + + +### instance\_id + +Return the unique instance id. + + + +### is\_measurement + +Whether the StateFn object is a measurement Operator. + + + +### num\_qubits + + + +### parameters + + + +### primitive + +`Statevector` + +The primitive which defines the behavior of the underlying State function. + + + +### settings + +Return settings. + +## Methods + +### add + + + +`add(other)` + +Return Operator addition of self and other, overloaded by `+`. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – An `OperatorBase` with the same number of qubits as self, and in the same ‘Operator’, ‘State function’, or ‘Measurement’ category as self (i.e. the same type of underlying function). + +**Returns** + +An `OperatorBase` equivalent to the sum of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### adjoint + + + +`adjoint()` + +Return a new Operator equal to the Operator’s adjoint (conjugate transpose), overloaded by `~`. For StateFns, this also turns the StateFn into a measurement. + +**Returns** + +An `OperatorBase` equivalent to the adjoint of self. + +**Return type** + +[*VectorStateFn*](#qiskit.opflow.state_fns.VectorStateFn "qiskit.opflow.state_fns.vector_state_fn.VectorStateFn") + +### eval + + + +`eval(front=None)` + +Evaluate the Operator’s underlying function, either on a binary string or another Operator. A square binary Operator can be defined as a function taking a binary function to another binary function. This method returns the value of that function for a given StateFn or binary string. For example, `op.eval('0110').eval('1110')` can be seen as querying the Operator’s matrix representation by row 6 and column 14, and will return the complex value at those “indices.” Similarly for a StateFn, `op.eval('1011')` will return the complex value at row 11 of the vector representation of the StateFn, as all StateFns are defined to be evaluated from Zero implicitly (i.e. it is as if `.eval('0000')` is already called implicitly to always “indexing” from column 0). + +If `front` is None, the matrix-representation of the operator is returned. + +**Parameters** + +**front** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") *|*[*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") *| None*) – The bitstring, dict of bitstrings (with values being coefficients), or StateFn to evaluated by the Operator’s underlying function, or None. + +**Returns** + +The output of the Operator’s evaluation function. If self is a `StateFn`, the result is a float or complex. If self is an Operator (`PrimitiveOp, ComposedOp, SummedOp, EvolvedOp,` etc.), the result is a StateFn. If `front` is None, the matrix-representation of the operator is returned, which is a `MatrixOp` for the operators and a `VectorStateFn` for state-functions. If either self or front contain proper `ListOps` (not ListOp subclasses), the result is an n-dimensional list of complex or StateFn results, resulting from the recursive evaluation by each OperatorBase in the ListOps. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") | [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### permute + + + +`permute(permutation)` + +Permute the qubits of the state function. + +**Parameters** + +**permutation** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A list defining where each qubit should be permuted. The qubit at index j of the circuit should be permuted to position permutation\[j]. + +**Returns** + +A new StateFn containing the permuted primitive. + +**Return type** + +[*VectorStateFn*](#qiskit.opflow.state_fns.VectorStateFn "qiskit.opflow.state_fns.vector_state_fn.VectorStateFn") + +### primitive\_strings + + + +`primitive_strings()` + +Return a set of strings describing the primitives contained in the Operator. For example, `{'QuantumCircuit', 'Pauli'}`. For hierarchical Operators, such as `ListOps`, this can help illuminate the primitives represented in the various recursive levels, and therefore which conversions can be applied. + +**Returns** + +A set of strings describing the primitives contained within the Operator. + +**Return type** + +[*Set*](https://docs.python.org/3/library/typing.html#typing.Set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### sample + + + +`sample(shots=1024, massive=False, reverse_endianness=False)` + +Sample the state function as a normalized probability distribution. Returns dict of bitstrings in order of probability, with values being probability. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of samples to take to approximate the State function. +* **massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. +* **reverse\_endianness** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to reverse the endianness of the bitstrings in the return dict to match Terra’s big-endianness. + +**Returns** + +A dict containing pairs sampled strings from the State function and sampling frequency divided by shots. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### tensor + + + +`tensor(other)` + +Return tensor product between self and other, overloaded by `^`. Note: You must be conscious of Qiskit’s big-endian bit printing convention. Meaning, Plus.tensor(Zero) produces a |+⟩ on qubit 0 and a |0⟩ on qubit 1, or |+⟩⨂|0⟩, but would produce a QuantumCircuit like + +> |0⟩– |+⟩– + +Because Terra prints circuits and results with qubit 0 at the end of the string or circuit. + +**Parameters** + +**other** ([*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase")) – The `OperatorBase` to tensor product with self. + +**Returns** + +An `OperatorBase` equivalent to the tensor product of self and other. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_circuit\_op + + + +`to_circuit_op()` + +Return `StateFnCircuit` corresponding to this StateFn. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + +### to\_density\_matrix + + + +`to_density_matrix(massive=False)` + +Return matrix representing product of StateFn evaluated on pairs of basis states. Overridden by child classes. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +The NumPy array representing the density matrix of the State function. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If massive is set to False, and exponentially large computation is needed. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_dict\_fn + + + +`to_dict_fn()` + +Creates the equivalent state function of type DictStateFn. + +**Returns** + +A new DictStateFn equivalent to `self`. + +**Return type** + +[*StateFn*](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.state_fn.StateFn") + +### to\_matrix + + + +`to_matrix(massive=False)` + +Return NumPy representation of the Operator. Represents the evaluation of the Operator’s underlying function on every combination of basis binary strings. Warn if more than 16 qubits to force having to set `massive=True` if such a large vector is desired. + +**Returns** + +The NumPy `ndarray` equivalent to this Operator. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### to\_matrix\_op + + + +`to_matrix_op(massive=False)` + +Return a `VectorStateFn` for this `StateFn`. + +**Parameters** + +**massive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to allow large conversions, e.g. creating a matrix representing over 16 qubits. + +**Returns** + +A VectorStateFn equivalent to self. + +**Return type** + +[*OperatorBase*](qiskit.opflow.OperatorBase "qiskit.opflow.operator_base.OperatorBase") + diff --git a/docs/api/qiskit/0.46/qiskit.opflow.state_fns.md b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.md new file mode 100644 index 00000000000..17a36c8009d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.opflow.state_fns.md @@ -0,0 +1,50 @@ +--- +title: state_fns +description: API reference for qiskit.opflow.state_fns +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.opflow.state_fns +--- + + + + + +# qiskit.opflow\.state\_fns + + + +## State Functions + + + +`qiskit.opflow.state_fns` + + + The [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow") module is deprecated and will be removed no earlier than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/opflow\_migration](https://qisk.it/opflow_migration). + + +State functions are defined to be complex functions over a single binary string (as compared to an operator, which is defined as a function over two binary strings, or a function taking a binary function to another binary function). This function may be called by the eval() method. + +Measurements are defined to be functionals over StateFns, taking them to real values. Generally, this real value is interpreted to represent the probability of some classical state (binary string) being observed from a probabilistic or quantum system represented by a StateFn. This leads to the equivalent definition, which is that a measurement m is a function over binary strings producing StateFns, such that the probability of measuring a given binary string b from a system with StateFn f is equal to the inner product between f and m(b). + + + All mathematical methods between StateFns are not in-place, meaning that they return a new object, but the underlying primitives are not copied. + + + + State functions here are not restricted to wave functions, as there is no requirement of normalization. + + +### State Functions + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`StateFn`](qiskit.opflow.state_fns.StateFn "qiskit.opflow.state_fns.StateFn")(\[primitive, coeff, is\_measurement]) | Deprecated: A class for representing state functions and measurements. | +| [`CircuitStateFn`](qiskit.opflow.state_fns.CircuitStateFn "qiskit.opflow.state_fns.CircuitStateFn")(\*args, \*\*kwargs) | Deprecated: A class for state functions and measurements which are defined by the action of a QuantumCircuit starting from \|0⟩, and stored using Terra's `QuantumCircuit` class. | +| [`DictStateFn`](qiskit.opflow.state_fns.DictStateFn "qiskit.opflow.state_fns.DictStateFn")(\*args, \*\*kwargs) | Deprecated: A class for state functions and measurements which are defined by a lookup table, stored in a dict. | +| [`VectorStateFn`](qiskit.opflow.state_fns.VectorStateFn "qiskit.opflow.state_fns.VectorStateFn")(\*args, \*\*kwargs) | Deprecated: A class for state functions and measurements which are defined in vector representation, and stored using Terra's `Statevector` class. | +| [`SparseVectorStateFn`](qiskit.opflow.state_fns.SparseVectorStateFn "qiskit.opflow.state_fns.SparseVectorStateFn")(\*args, \*\*kwargs) | Deprecated: A class for sparse state functions and measurements in vector representation. | +| [`OperatorStateFn`](qiskit.opflow.state_fns.OperatorStateFn "qiskit.opflow.state_fns.OperatorStateFn")(\*args, \*\*kwargs) | Deprecated: A class for state functions and measurements which are defined by a density Operator, stored using an `OperatorBase`. | +| [`CVaRMeasurement`](qiskit.opflow.state_fns.CVaRMeasurement "qiskit.opflow.state_fns.CVaRMeasurement")(\*args, \*\*kwargs) | Deprecated: A specialized measurement class to compute CVaR expectation values. | + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.BaseController.md b/docs/api/qiskit/0.46/qiskit.passmanager.BaseController.md new file mode 100644 index 00000000000..e7c19d26414 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.BaseController.md @@ -0,0 +1,73 @@ +--- +title: BaseController +description: API reference for qiskit.passmanager.BaseController +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.BaseController +--- + +# BaseController + + + +`qiskit.passmanager.BaseController(options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/base_tasks.py "view source code") + +Bases: `Task`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class of controller. + +A controller is built with a collection of pass manager tasks, and a subclass provides a custom logic to choose next task to run. Note a controller can be nested into another controller, and a controller itself doesn’t provide any subroutine to modify the input IR. + +Create new flow controller. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – Option for this flow controller. + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### iter\_tasks + + + +`abstract iter_tasks(state)` + +A custom logic to choose a next task to run. + +Controller subclass can consume the state to build a proper task pipeline. The updated state after a task execution will be fed back in as the “return” value of any `yield` statements. This indicates the order of task execution is only determined at running time. This method is not allowed to mutate the given state object. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. + +**Yields** + +*Task* – Next task to run. + +**Return type** + +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.BasePassManager.md b/docs/api/qiskit/0.46/qiskit.passmanager.BasePassManager.md new file mode 100644 index 00000000000..a5a9ca4523b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.BasePassManager.md @@ -0,0 +1,141 @@ +--- +title: BasePassManager +description: API reference for qiskit.passmanager.BasePassManager +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.BasePassManager +--- + +# BasePassManager + + + +`qiskit.passmanager.BasePassManager(tasks=(), max_iteration=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/passmanager.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Pass manager base class. + +Initialize an empty pass manager object. + +**Parameters** + +* **tasks** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A pass set to be added to the pass manager schedule. +* **max\_iteration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of iterations the schedule will be looped if the condition is not met. + +## Methods + +### append + + + +`append(tasks)` + +Append tasks to the schedule of passes. + +**Parameters** + +**tasks** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A set of pass manager tasks to be added to schedule. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – When any element of tasks is not a subclass of passmanager Task. + +### remove + + + +`remove(index)` + +Removes a particular pass in the scheduler. + +**Parameters** + +**index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Pass index to remove, based on the position in `passes()`. + +**Raises** + +[**PassManagerError**](passmanager#qiskit.passmanager.PassManagerError "qiskit.passmanager.PassManagerError") – If the index is not found. + +### replace + + + +`replace(index, tasks)` + +Replace a particular pass in the scheduler. + +**Parameters** + +* **index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Task index to replace, based on the position in `tasks()` +* **tasks** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A set of pass manager tasks to be added to schedule. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – When any element of tasks is not a subclass of passmanager Task. +* [**PassManagerError**](passmanager#qiskit.passmanager.PassManagerError "qiskit.passmanager.PassManagerError") – If the index is not found. + +### run + + + +`run(in_programs, callback=None, **kwargs)` + +Run all the passes on the specified `in_programs`. + +**Parameters** + +* **in\_programs** (*Any |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Any]*) – Input programs to transform via all the registered passes. A single input object cannot be a Python builtin list object. A list object is considered as multiple input objects to optimize. + +* **callback** (*Callable*) – + + A callback function that will be called after each pass execution. The function will be called with 4 keyword arguments: + + ```python + task (GenericPass): the pass being run + passmanager_ir (Any): depending on pass manager subclass + property_set (PropertySet): the property set + running_time (float): the time to execute the pass + count (int): the index for the pass execution + ``` + + The exact arguments pass expose the internals of the pass manager and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases be sure to check that the arguments being passed are the same. + + To use the callback feature you define a function that will take in kwargs dict and access the variables. For example: + + ```python + def callback_func(**kwargs): + task = kwargs['task'] + passmanager_ir = kwargs['passmanager_ir'] + property_set = kwargs['property_set'] + running_time = kwargs['running_time'] + count = kwargs['count'] + ... + ``` + +* **kwargs** – Arbitrary arguments passed to the compiler frontend and backend. + +**Returns** + +The transformed program(s). + +**Return type** + +Any + +### to\_flow\_controller + + + +`to_flow_controller()` + +Linearize this manager into a single [`FlowControllerLinear`](qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.FlowControllerLinear"), so that it can be nested inside another pass manager. + +**Returns** + +A linearized pass manager. + +**Return type** + +[*FlowControllerLinear*](qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.flow_controllers.FlowControllerLinear") + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.ConditionalController.md b/docs/api/qiskit/0.46/qiskit.passmanager.ConditionalController.md new file mode 100644 index 00000000000..d889dfc2896 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.ConditionalController.md @@ -0,0 +1,95 @@ +--- +title: ConditionalController +description: API reference for qiskit.passmanager.ConditionalController +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.ConditionalController +--- + +# ConditionalController + + + +`qiskit.passmanager.ConditionalController(tasks=(), condition=None, *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/flow_controllers.py "view source code") + +Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") + +A flow controller runs the pipeline once if the condition is true, or does nothing if the condition is false. + +Create new flow controller. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – Option for this flow controller. + +## Attributes + + + +### passes + +Alias of tasks for backward compatibility. + +## Methods + +### append + + + +`append(passes)` + +Add new task to pipeline. + + + The method `qiskit.passmanager.flow_controllers.ConditionalController.append()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. All tasks must be provided at construction time of the controller object. + + +**Parameters** + +**passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A new task or list of tasks to add. + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### iter\_tasks + + + +`iter_tasks(state)` + +A custom logic to choose a next task to run. + +Controller subclass can consume the state to build a proper task pipeline. The updated state after a task execution will be fed back in as the “return” value of any `yield` statements. This indicates the order of task execution is only determined at running time. This method is not allowed to mutate the given state object. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. + +**Yields** + +*Task* – Next task to run. + +**Return type** + +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.DoWhileController.md b/docs/api/qiskit/0.46/qiskit.passmanager.DoWhileController.md new file mode 100644 index 00000000000..20ce34f6c77 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.DoWhileController.md @@ -0,0 +1,97 @@ +--- +title: DoWhileController +description: API reference for qiskit.passmanager.DoWhileController +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.DoWhileController +--- + +# DoWhileController + + + +`qiskit.passmanager.DoWhileController(tasks=(), do_while=None, *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/flow_controllers.py "view source code") + +Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") + +Run the given tasks in a loop until the `do_while` condition on the property set becomes `False`. + +The given tasks will always run at least once, and on iteration of the loop, all the tasks will be run (with the exception of a failure state being set). + +Create new flow controller. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – Option for this flow controller. + +## Attributes + + + +### passes + +Alias of tasks for backward compatibility. + +## Methods + +### append + + + +`append(passes)` + +Add new task to pipeline. + + + The method `qiskit.passmanager.flow_controllers.DoWhileController.append()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. All tasks must be provided at construction time of the controller object. + + +**Parameters** + +**passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A new task or list of tasks to add. + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### iter\_tasks + + + +`iter_tasks(state)` + +A custom logic to choose a next task to run. + +Controller subclass can consume the state to build a proper task pipeline. The updated state after a task execution will be fed back in as the “return” value of any `yield` statements. This indicates the order of task execution is only determined at running time. This method is not allowed to mutate the given state object. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. + +**Yields** + +*Task* – Next task to run. + +**Return type** + +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.FlowController.md b/docs/api/qiskit/0.46/qiskit.passmanager.FlowController.md new file mode 100644 index 00000000000..9d4a3323f1e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.FlowController.md @@ -0,0 +1,168 @@ +--- +title: FlowController +description: API reference for qiskit.passmanager.FlowController +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.FlowController +--- + +# FlowController + + + +`qiskit.passmanager.FlowController(options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/flow_controllers.py "view source code") + +Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") + +A legacy factory for other flow controllers. + + + This class is primarily for compatibility with legacy versions of Qiskit, and in general, you should prefer simply instantiating the controller you want, and adding it to the relevant [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") or other controller. Its use is deprecated. + + +This allows syntactic sugar for writing pipelines. For example: + +```python +FlowController.add_flow_controller("my_condition", CustomController) + +controller = FlowController.controller_factory( + [PassA(), PassB()], + {"max_iteration": 1000}, + condition=lambda prop_set: prop_set["x"] == 0, + do_while=lambda prop_set: prop_set["x"] < 100, + my_condition=lambda prop_set: prop_set["y"] = "abc", +) +``` + +This creates a nested flow controller that runs when the value `x` in the [`PropertySet`](qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") is zero and repeats the pipeline until the value becomes 100. In each innermost loop, the custom iteration condition provided by the `CustomController` is also evaluated. + + + [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.BaseController") must be directly subclassed to define a custom flow controller. This class provides a controller factory method, which consumes a class variable [`registered_controllers`](#qiskit.passmanager.FlowController.registered_controllers "qiskit.passmanager.FlowController.registered_controllers"). Subclassing FlowController may cause unexpected behavior in the factory method. Note that factory method implicitly determines the priority of the builtin controllers when multiple controllers are called together, and the behavior of generated controller is hardly debugged. + + + + The class `qiskit.passmanager.flow_controllers.FlowController` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0 release. The base class of flow controller is now qiskit.passmanager.BaseController. This class exists only for the controller namespace used to map a controller name tothe corresponding class object, which is used to instantiate a controller with keyword argument in PassManager.append method. This pattern was also deprecated. + + +## Attributes + + + +### hierarchy + +`= ['condition', 'do_while']` + + + +### registered\_controllers = \{'condition' + +`= {'condition':` + +`= {'condition': , 'do_while': }` + +## Methods + +### add\_flow\_controller + + + +`classmethod add_flow_controller(name, controller)` + +Adds a flow controller. + + + The method `qiskit.passmanager.flow_controllers.FlowController.add_flow_controller()` is deprecated as of qiskit 0.45.0. It will be removed in the 1.0 release. The controller factory method is deprecated and managing the custom flow controllers with aliases no longer helps building the task pipeline. Controllers must be explicitly instantiated and appended to the pipeline. + + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Alias of controller class in the namespace. +* **controller** ([*Type*](https://docs.python.org/3/library/typing.html#typing.Type "(in Python v3.12)")*\[*[*BaseController*](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController")*]*) – Flow controller class. + +### controller\_factory + + + +`classmethod controller_factory(passes, options, **controllers)` + +Create a new flow controller with normalization. + + + The method `qiskit.passmanager.flow_controllers.FlowController.controller_factory()` is deprecated as of qiskit 0.45.0. It will be removed in the 1.0 release. FlowController objects must be explicitly instantiated. Building controllers with keyword arguments ignores the order when multiple keyword arguments are provided together, which is likely unsafe. + + +**Parameters** + +* **passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A list of optimization tasks. +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Option for this flow controller. +* **controllers** – Dictionary of controller callables keyed on flow controller alias. + +**Returns** + +An instance of normalized flow controller. + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### iter\_tasks + + + +`abstract iter_tasks(state)` + +A custom logic to choose a next task to run. + +Controller subclass can consume the state to build a proper task pipeline. The updated state after a task execution will be fed back in as the “return” value of any `yield` statements. This indicates the order of task execution is only determined at running time. This method is not allowed to mutate the given state object. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. + +**Yields** + +*Task* – Next task to run. + +**Return type** + +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] + +### remove\_flow\_controller + + + +`classmethod remove_flow_controller(name)` + +Removes a flow controller. + + + The method `qiskit.passmanager.flow_controllers.FlowController.remove_flow_controller()` is deprecated as of qiskit 0.45.0. It will be removed in the 1.0 release. The controller factory method is deprecated and managing the custom flow controllers with aliases no longer helps building the task pipeline. Controllers must be explicitly instantiated and appended to the pipeline. + + +**Parameters** + +**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Alias of the controller to remove. + +**Raises** + +[**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.12)") – If the controller to remove was not registered. + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.FlowControllerLinear.md b/docs/api/qiskit/0.46/qiskit.passmanager.FlowControllerLinear.md new file mode 100644 index 00000000000..78c2403a6cc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.FlowControllerLinear.md @@ -0,0 +1,95 @@ +--- +title: FlowControllerLinear +description: API reference for qiskit.passmanager.FlowControllerLinear +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.FlowControllerLinear +--- + +# FlowControllerLinear + + + +`qiskit.passmanager.FlowControllerLinear(tasks=(), *, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/flow_controllers.py "view source code") + +Bases: [`BaseController`](qiskit.passmanager.BaseController "qiskit.passmanager.base_tasks.BaseController") + +A standard flow controller that runs tasks one after the other. + +Create new flow controller. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – Option for this flow controller. + +## Attributes + + + +### passes + +Alias of tasks for backward compatibility. + +## Methods + +### append + + + +`append(passes)` + +Add new task to pipeline. + + + The method `qiskit.passmanager.flow_controllers.FlowControllerLinear.append()` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. All tasks must be provided at construction time of the controller object. + + +**Parameters** + +**passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A new task or list of tasks to add. + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### iter\_tasks + + + +`iter_tasks(state)` + +A custom logic to choose a next task to run. + +Controller subclass can consume the state to build a proper task pipeline. The updated state after a task execution will be fed back in as the “return” value of any `yield` statements. This indicates the order of task execution is only determined at running time. This method is not allowed to mutate the given state object. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – The state of the passmanager workflow at the beginning of this flow controller’s execution. +* **state** – the state of pass manager after the execution of the last task that was yielded. The generator does not need to inspect this if it is irrelevant to its logic, nor update it. + +**Yields** + +*Task* – Next task to run. + +**Return type** + +[*Generator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Generator "(in Python v3.12)")\[*Task*, [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState"), None] + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.GenericPass.md b/docs/api/qiskit/0.46/qiskit.passmanager.GenericPass.md new file mode 100644 index 00000000000..20f324c196d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.GenericPass.md @@ -0,0 +1,97 @@ +--- +title: GenericPass +description: API reference for qiskit.passmanager.GenericPass +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.GenericPass +--- + +# GenericPass + + + +`qiskit.passmanager.GenericPass`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/base_tasks.py "view source code") + +Bases: `Task`, [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class of a single pass manager task. + +A pass instance can read and write to the provided [`PropertySet`](qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet"), and may modify the input pass manager IR. + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`abstract run(passmanager_ir)` + +Run optimization task. + +**Parameters** + +**passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. + +**Returns** + +Optimized Qiskit IR. + +**Return type** + +[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.PassManagerState.md b/docs/api/qiskit/0.46/qiskit.passmanager.PassManagerState.md new file mode 100644 index 00000000000..4d876b0c43d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.PassManagerState.md @@ -0,0 +1,40 @@ +--- +title: PassManagerState +description: API reference for qiskit.passmanager.PassManagerState +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.PassManagerState +--- + +# PassManagerState + + + +`qiskit.passmanager.PassManagerState(workflow_status, property_set)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/compilation_status.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A portable container object that pass manager tasks communicate through generator. + +This object can contain every information about the running pass manager workflow, except for the IR object being optimized. The data structure consists of two elements; one for the status of the workflow itself, and another one for the additional information about the IR analyzed through pass executions. This container aims at just providing a robust interface for the `Task.execute()`, and no logic that modifies the container elements must be implemented. + +This object is mutable, and might be mutated by pass executions. + +## Attributes + + + +### workflow\_status + +`WorkflowStatus` + +Status of the current compilation workflow. + + + +### property\_set + +`PropertySet` + +Information about IR being optimized. + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.PropertySet.md b/docs/api/qiskit/0.46/qiskit.passmanager.PropertySet.md new file mode 100644 index 00000000000..735c0e8b0b3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.PropertySet.md @@ -0,0 +1,102 @@ +--- +title: PropertySet +description: API reference for qiskit.passmanager.PropertySet +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.PropertySet +--- + +# PropertySet + + + +`qiskit.passmanager.PropertySet`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/compilation_status.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +A default dictionary-like object. + +## Methods + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.passmanager.WorkflowStatus.md b/docs/api/qiskit/0.46/qiskit.passmanager.WorkflowStatus.md new file mode 100644 index 00000000000..9b1711c7bc8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.passmanager.WorkflowStatus.md @@ -0,0 +1,50 @@ +--- +title: WorkflowStatus +description: API reference for qiskit.passmanager.WorkflowStatus +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.passmanager.WorkflowStatus +--- + +# WorkflowStatus + + + +`qiskit.passmanager.WorkflowStatus(count=0, completed_passes=, previous_run=RunState.FAIL)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/passmanager/compilation_status.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Collection of compilation status of workflow, i.e. pass manager run. + +This data structure is initialized when the pass manager is run, and recursively handed over to underlying tasks. Each pass will update this status once after being executed, and the lifetime of the workflow status object is the time during which the pass manager is running. + +## Attributes + + + +### count + +`int` + +`= 0` + +Current number of pass execution. + + + +### previous\_run + +`RunState` + +`= 1` + +Status of the latest pass run. + + + +### completed\_passes + +`set` + +Passes already run that have not been invalidated. + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.BackendEstimator.md b/docs/api/qiskit/0.46/qiskit.primitives.BackendEstimator.md new file mode 100644 index 00000000000..698aae34ecd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.BackendEstimator.md @@ -0,0 +1,172 @@ +--- +title: BackendEstimator +description: API reference for qiskit.primitives.BackendEstimator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.BackendEstimator +--- + +# BackendEstimator + + + +`qiskit.primitives.BackendEstimator(backend, options=None, abelian_grouping=True, bound_pass_manager=None, skip_transpilation=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/backend_estimator.py "view source code") + +Bases: [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.base.base_estimator.BaseEstimator")\[`PrimitiveJob`\[[`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.base.estimator_result.EstimatorResult")]] + +Evaluates expectation value using Pauli rotation gates. + +The [`BackendEstimator`](#qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator") class is a generic implementation of the [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") interface that is used to wrap a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") (or [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1")) object in the [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") API. It facilitates using backends that do not provide a native [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator") implementation in places that work with [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"), such as algorithms in [`qiskit.algorithms`](algorithms#module-qiskit.algorithms "qiskit.algorithms") including [`VQE`](qiskit.algorithms.minimum_eigensolvers.VQE "qiskit.algorithms.minimum_eigensolvers.VQE"). However, if you’re using a provider that has a native implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"), it is a better choice to leverage that native implementation as it will likely include additional optimizations and be a more efficient implementation. The generic nature of this class precludes doing any provider- or backend-specific optimizations. + +Initialize a new BackendEstimator instance + +**Parameters** + +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.BackendV2")) – Required: the backend to run the primitive on +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. +* **abelian\_grouping** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the observable should be grouped into commuting +* **bound\_pass\_manager** ([*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") *| None*) – An optional pass manager to run after parameter binding. +* **skip\_transpilation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If this is set to True the internal compilation of the input circuits is skipped and the circuit objects will be directly executed when this object is called. + +## Attributes + + + +### backend + +Returns: The backend which this estimator object based on + + + +### circuits + +Quantum circuits that represents quantum states. + +**Returns** + +The quantum circuits. + + + +### observables + +Observables to be estimated. + +**Returns** + +The observables. + + + +### options + +Return options values for the estimator. + +**Returns** + +options + + + +### parameters + +Parameters of the quantum circuits. + +**Returns** + +Parameters, where `parameters[i][j]` is the j-th parameter of the i-th circuit. + + + +### preprocessed\_circuits + +Transpiled quantum circuits produced by preprocessing :returns: List of the transpiled quantum circuit + + + +### transpile\_options + +Return the transpiler options for transpiling the circuits. + + + +### transpiled\_circuits + +Transpiled quantum circuits. :returns: List of the transpiled quantum circuit + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instance has been closed. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values=None, **run_options)` + +Run the job of the estimation of expectation value(s). + +`circuits`, `observables`, and `parameter_values` should have the same length. The i-th element of the result is the expectation of observable + +```python +obs = observables[i] +``` + +for the state prepared by + +```python +circ = circuits[i] +``` + +with bound parameters + +```python +values = parameter_values[i]. +``` + + + Implicit conversion from a `PauliList` to a `SparsePauliOp` with `coeffs=1` in the `observables` arguments is deprecated as of Qiskit 0.46 and will be removed in Qiskit 1.0. You should explicitly convert to a `SparsePauli` using `SparsePauliOp(pauli_list)` to avoid this warning. + + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] |* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – one or more circuit objects. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – one or more observable objects. Several formats are allowed; importantly, `str` should follow the string representation format for [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") objects. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – concrete parameters to be bound. +* **run\_options** – runtime options used for circuit execution. + +**Returns** + +The job object of EstimatorResult. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Invalid argument type given. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid argument values given. + +**Return type** + +T + +### set\_options + + + +`set_options(**fields)` + +Set options values for the estimator. + +**Parameters** + +**\*\*fields** – The fields to update the options + +### set\_transpile\_options + + + +`set_transpile_options(**fields)` + +Set the transpiler options for transpiler. :param \*\*fields: The fields to update the options + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.BackendSampler.md b/docs/api/qiskit/0.46/qiskit.primitives.BackendSampler.md new file mode 100644 index 00000000000..b10f1c3958e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.BackendSampler.md @@ -0,0 +1,153 @@ +--- +title: BackendSampler +description: API reference for qiskit.primitives.BackendSampler +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.BackendSampler +--- + +# BackendSampler + + + +`qiskit.primitives.BackendSampler(backend, options=None, bound_pass_manager=None, skip_transpilation=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/backend_sampler.py "view source code") + +Bases: [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.base.base_sampler.BaseSampler")\[`PrimitiveJob`\[[`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.base.sampler_result.SamplerResult")]] + +A [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") implementation that provides an interface for leveraging the sampler interface from any backend. + +This class provides a sampler interface from any backend and doesn’t do any measurement mitigation, it just computes the probability distribution from the counts. It facilitates using backends that do not provide a native [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") implementation in places that work with [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler"), such as algorithms in [`qiskit.algorithms`](algorithms#module-qiskit.algorithms "qiskit.algorithms") including [`SamplingVQE`](qiskit.algorithms.minimum_eigensolvers.SamplingVQE "qiskit.algorithms.minimum_eigensolvers.SamplingVQE"). However, if you’re using a provider that has a native implementation of [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler"), it is a better choice to leverage that native implementation as it will likely include additional optimizations and be a more efficient implementation. The generic nature of this class precludes doing any provider- or backend-specific optimizations. + +Initialize a new BackendSampler + +**Parameters** + +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.BackendV2")) – Required: the backend to run the sampler primitive on +* **options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. +* **bound\_pass\_manager** ([*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") *| None*) – An optional pass manager to run after parameter binding. +* **skip\_transpilation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If this is set to True the internal compilation of the input circuits is skipped and the circuit objects will be directly executed when this objected is called. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If backend is not provided + +## Attributes + + + +### backend + +Returns: The backend which this sampler object based on + + + +### circuits + +Quantum circuits to be sampled. + +**Returns** + +The quantum circuits to be sampled. + + + +### options + +Return options values for the estimator. + +**Returns** + +options + + + +### parameters + +Parameters of quantum circuits. + +**Returns** + +List of the parameters in each quantum circuit. + + + +### preprocessed\_circuits + +Preprocessed quantum circuits produced by preprocessing :returns: List of the transpiled quantum circuit + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instance has been closed. + + + +### transpile\_options + +Return the transpiler options for transpiling the circuits. + + + +### transpiled\_circuits + +Transpiled quantum circuits. :returns: List of the transpiled quantum circuit + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instance has been closed. + +## Methods + +### run + + + +`run(circuits, parameter_values=None, **run_options)` + +Run the job of the sampling of bitstrings. + +**Parameters** + +* **circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – One of more circuit objects. +* **parameter\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Parameters to be bound to the circuit. +* **run\_options** – Backend runtime options used for circuit execution. + +**Returns** + +The job object of the result of the sampler. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +T + +### set\_options + + + +`set_options(**fields)` + +Set options values for the estimator. + +**Parameters** + +**\*\*fields** – The fields to update the options + +### set\_transpile\_options + + + +`set_transpile_options(**fields)` + +Set the transpiler options for transpiler. :param \*\*fields: The fields to update the options. + +**Returns** + +self. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instance has been closed. + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.BaseEstimator.md b/docs/api/qiskit/0.46/qiskit.primitives.BaseEstimator.md new file mode 100644 index 00000000000..e1a0f4cdf54 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.BaseEstimator.md @@ -0,0 +1,132 @@ +--- +title: BaseEstimator +description: API reference for qiskit.primitives.BaseEstimator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.BaseEstimator +--- + +# BaseEstimator + + + +`qiskit.primitives.BaseEstimator(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/base/base_estimator.py "view source code") + +Bases: `BasePrimitive`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic "(in Python v3.12)")\[`T`] + +Estimator base class. + +Base class for Estimator that estimates expectation values of quantum circuits and observables. + +Creating an instance of an Estimator, or using one in a `with` context opens a session that holds resources until the instance is `close()` ed or the context is exited. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. + +## Attributes + + + +### circuits + +Quantum circuits that represents quantum states. + +**Returns** + +The quantum circuits. + + + +### observables + +Observables to be estimated. + +**Returns** + +The observables. + + + +### options + +Return options values for the estimator. + +**Returns** + +options + + + +### parameters + +Parameters of the quantum circuits. + +**Returns** + +Parameters, where `parameters[i][j]` is the j-th parameter of the i-th circuit. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values=None, **run_options)` + +Run the job of the estimation of expectation value(s). + +`circuits`, `observables`, and `parameter_values` should have the same length. The i-th element of the result is the expectation of observable + +```python +obs = observables[i] +``` + +for the state prepared by + +```python +circ = circuits[i] +``` + +with bound parameters + +```python +values = parameter_values[i]. +``` + + + Implicit conversion from a `PauliList` to a `SparsePauliOp` with `coeffs=1` in the `observables` arguments is deprecated as of Qiskit 0.46 and will be removed in Qiskit 1.0. You should explicitly convert to a `SparsePauli` using `SparsePauliOp(pauli_list)` to avoid this warning. + + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] |* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – one or more circuit objects. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – one or more observable objects. Several formats are allowed; importantly, `str` should follow the string representation format for [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") objects. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – concrete parameters to be bound. +* **run\_options** – runtime options used for circuit execution. + +**Returns** + +The job object of EstimatorResult. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Invalid argument type given. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid argument values given. + +**Return type** + +T + +### set\_options + + + +`set_options(**fields)` + +Set options values for the estimator. + +**Parameters** + +**\*\*fields** – The fields to update the options + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.BaseSampler.md b/docs/api/qiskit/0.46/qiskit.primitives.BaseSampler.md new file mode 100644 index 00000000000..a2634c0d2c9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.BaseSampler.md @@ -0,0 +1,96 @@ +--- +title: BaseSampler +description: API reference for qiskit.primitives.BaseSampler +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.BaseSampler +--- + +# BaseSampler + + + +`qiskit.primitives.BaseSampler(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/base/base_sampler.py "view source code") + +Bases: `BasePrimitive`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic "(in Python v3.12)")\[`T`] + +Sampler base class + +Base class of Sampler that calculates quasi-probabilities of bitstrings from quantum circuits. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. + +## Attributes + + + +### circuits + +Quantum circuits to be sampled. + +**Returns** + +The quantum circuits to be sampled. + + + +### options + +Return options values for the estimator. + +**Returns** + +options + + + +### parameters + +Parameters of quantum circuits. + +**Returns** + +List of the parameters in each quantum circuit. + +## Methods + +### run + + + +`run(circuits, parameter_values=None, **run_options)` + +Run the job of the sampling of bitstrings. + +**Parameters** + +* **circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – One of more circuit objects. +* **parameter\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Parameters to be bound to the circuit. +* **run\_options** – Backend runtime options used for circuit execution. + +**Returns** + +The job object of the result of the sampler. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +T + +### set\_options + + + +`set_options(**fields)` + +Set options values for the estimator. + +**Parameters** + +**\*\*fields** – The fields to update the options + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.Estimator.md b/docs/api/qiskit/0.46/qiskit.primitives.Estimator.md new file mode 100644 index 00000000000..997c9dcd96d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.Estimator.md @@ -0,0 +1,137 @@ +--- +title: Estimator +description: API reference for qiskit.primitives.Estimator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.Estimator +--- + +# Estimator + + + +`qiskit.primitives.Estimator(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/estimator.py "view source code") + +Bases: [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.base.base_estimator.BaseEstimator")\[`PrimitiveJob`\[[`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.base.estimator_result.EstimatorResult")]] + +Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"). + +**Run Options** + +* **shots** (None or int) – The number of shots. If None, it calculates the exact expectation values. Otherwise, it samples from normal distributions with standard errors as standard deviations using normal distribution approximation. +* **seed** (np.random.Generator or int) – Set a fixed seed or generator for the normal distribution. If shots is None, this option is ignored. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if some classical bits are not used for measurements. + +## Attributes + + + +### circuits + +Quantum circuits that represents quantum states. + +**Returns** + +The quantum circuits. + + + +### observables + +Observables to be estimated. + +**Returns** + +The observables. + + + +### options + +Return options values for the estimator. + +**Returns** + +options + + + +### parameters + +Parameters of the quantum circuits. + +**Returns** + +Parameters, where `parameters[i][j]` is the j-th parameter of the i-th circuit. + +## Methods + +### run + + + +`run(circuits, observables, parameter_values=None, **run_options)` + +Run the job of the estimation of expectation value(s). + +`circuits`, `observables`, and `parameter_values` should have the same length. The i-th element of the result is the expectation of observable + +```python +obs = observables[i] +``` + +for the state prepared by + +```python +circ = circuits[i] +``` + +with bound parameters + +```python +values = parameter_values[i]. +``` + + + Implicit conversion from a `PauliList` to a `SparsePauliOp` with `coeffs=1` in the `observables` arguments is deprecated as of Qiskit 0.46 and will be removed in Qiskit 1.0. You should explicitly convert to a `SparsePauli` using `SparsePauliOp(pauli_list)` to avoid this warning. + + +**Parameters** + +* **circuits** (*Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] |* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – one or more circuit objects. +* **observables** (*Sequence\[BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | BaseOperator |* [*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – one or more observable objects. Several formats are allowed; importantly, `str` should follow the string representation format for [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") objects. +* **parameter\_values** (*Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] |* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – concrete parameters to be bound. +* **run\_options** – runtime options used for circuit execution. + +**Returns** + +The job object of EstimatorResult. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – Invalid argument type given. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid argument values given. + +**Return type** + +T + +### set\_options + + + +`set_options(**fields)` + +Set options values for the estimator. + +**Parameters** + +**\*\*fields** – The fields to update the options + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.EstimatorResult.md b/docs/api/qiskit/0.46/qiskit.primitives.EstimatorResult.md new file mode 100644 index 00000000000..3ef9672c1ca --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.EstimatorResult.md @@ -0,0 +1,81 @@ +--- +title: EstimatorResult +description: API reference for qiskit.primitives.EstimatorResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.EstimatorResult +--- + +# EstimatorResult + + + +`qiskit.primitives.EstimatorResult(values, metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/base/estimator_result.py "view source code") + +Bases: `_BasePrimitiveResult` + +Result of Estimator. + +```python +result = estimator.run(circuits, observables, params).result() +``` + +where the i-th elements of `result` correspond to the circuit and observable given by `circuits[i]`, `observables[i]`, and the parameter values bounds by `params[i]`. For example, `results.values[i]` gives the expectation value, and `result.metadata[i]` is a metadata dictionary for this circuit and parameters. + +**Parameters** + +* **values** (*np.ndarray*) – The array of the expectation values. +* **metadata** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*]*) – List of the metadata. + +## Attributes + + + +### experiments + +Experiment data dicts in any inheriting result dataclass. + + + The property `qiskit.primitives.base.base_result._BasePrimitiveResult.experiments` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + + + +### num\_experiments + +Number of experiments in any inheriting result dataclass. + + + The property `qiskit.primitives.base.base_result._BasePrimitiveResult.num_experiments` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + + + +### values + +`np.ndarray[Any, np.dtype[np.float64]]` + + + +### metadata + +`list[dict[str, Any]]` + +## Methods + +### decompose + + + +`decompose()` + +Generate single experiment result objects from self. + + + The method `qiskit.primitives.base.base_result._BasePrimitiveResult.decompose()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + +**Return type** + +[*Iterator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator "(in Python v3.12)")\[*\_BasePrimitiveResult*] + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.Sampler.md b/docs/api/qiskit/0.46/qiskit.primitives.Sampler.md new file mode 100644 index 00000000000..e37a1dde922 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.Sampler.md @@ -0,0 +1,105 @@ +--- +title: Sampler +description: API reference for qiskit.primitives.Sampler +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.Sampler +--- + +# Sampler + + + +`qiskit.primitives.Sampler(*, options=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/sampler.py "view source code") + +Bases: [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.base.base_sampler.BaseSampler")\[`PrimitiveJob`\[[`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.base.sampler_result.SamplerResult")]] + +Sampler class. + +[`Sampler`](#qiskit.primitives.Sampler "qiskit.primitives.Sampler") is a reference implementation of [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler"). + +**Run Options** + +* **shots** (None or int) – The number of shots. If None, it calculates the probabilities. Otherwise, it samples from multinomial distributions. +* **seed** (np.random.Generator or int) – Set a fixed seed or generator for the multinomial distribution. If shots is None, this option is ignored. + +**Parameters** + +**options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Default options. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if some classical bits are not used for measurements. + +## Attributes + + + +### circuits + +Quantum circuits to be sampled. + +**Returns** + +The quantum circuits to be sampled. + + + +### options + +Return options values for the estimator. + +**Returns** + +options + + + +### parameters + +Parameters of quantum circuits. + +**Returns** + +List of the parameters in each quantum circuit. + +## Methods + +### run + + + +`run(circuits, parameter_values=None, **run_options)` + +Run the job of the sampling of bitstrings. + +**Parameters** + +* **circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *| Sequence\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – One of more circuit objects. +* **parameter\_values** (*Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | Sequence\[Sequence\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]] | None*) – Parameters to be bound to the circuit. +* **run\_options** – Backend runtime options used for circuit execution. + +**Returns** + +The job object of the result of the sampler. The i-th result corresponds to `circuits[i]` evaluated with parameters bound as `parameter_values[i]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid arguments are given. + +**Return type** + +T + +### set\_options + + + +`set_options(**fields)` + +Set options values for the estimator. + +**Parameters** + +**\*\*fields** – The fields to update the options + diff --git a/docs/api/qiskit/0.46/qiskit.primitives.SamplerResult.md b/docs/api/qiskit/0.46/qiskit.primitives.SamplerResult.md new file mode 100644 index 00000000000..0cc0ee6acda --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.primitives.SamplerResult.md @@ -0,0 +1,81 @@ +--- +title: SamplerResult +description: API reference for qiskit.primitives.SamplerResult +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.primitives.SamplerResult +--- + +# SamplerResult + + + +`qiskit.primitives.SamplerResult(quasi_dists, metadata)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/primitives/base/sampler_result.py "view source code") + +Bases: `_BasePrimitiveResult` + +Result of Sampler. + +```python +result = sampler.run(circuits, params).result() +``` + +where the i-th elements of `result` correspond to the circuit given by `circuits[i]`, and the parameter values bounds by `params[i]`. For example, `results.quasi_dists[i]` gives the quasi-probabilities of bitstrings, and `result.metadata[i]` is a metadata dictionary for this circuit and parameters. + +**Parameters** + +* **quasi\_dists** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*QuasiDistribution*](qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution")*]*) – List of the quasi-probabilities. +* **metadata** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*]*) – List of the metadata. + +## Attributes + + + +### experiments + +Experiment data dicts in any inheriting result dataclass. + + + The property `qiskit.primitives.base.base_result._BasePrimitiveResult.experiments` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + + + +### num\_experiments + +Number of experiments in any inheriting result dataclass. + + + The property `qiskit.primitives.base.base_result._BasePrimitiveResult.num_experiments` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + + + +### quasi\_dists + +`list[qiskit.result.distributions.quasi.QuasiDistribution]` + + + +### metadata + +`list[dict[str, Any]]` + +## Methods + +### decompose + + + +`decompose()` + +Generate single experiment result objects from self. + + + The method `qiskit.primitives.base.base_result._BasePrimitiveResult.decompose()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. + + +**Return type** + +[*Iterator*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator "(in Python v3.12)")\[*\_BasePrimitiveResult*] + diff --git a/docs/api/qiskit/0.46/qiskit.providers.Backend.md b/docs/api/qiskit/0.46/qiskit.providers.Backend.md new file mode 100644 index 00000000000..ccc88952e78 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.Backend.md @@ -0,0 +1,28 @@ +--- +title: Backend +description: API reference for qiskit.providers.Backend +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.Backend +--- + +# Backend + + + +`qiskit.providers.Backend`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/backend.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Base common type for all versioned Backend abstract classes. + +Note this class should not be inherited from directly, it is intended to be used for type checking. When implementing a provider you should use the versioned abstract classes as the parent class and not this class directly. + +## Attributes + + + +### version + +`= 0` + diff --git a/docs/api/qiskit/0.46/qiskit.providers.BackendV1.md b/docs/api/qiskit/0.46/qiskit.providers.BackendV1.md new file mode 100644 index 00000000000..535cb868e57 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.BackendV1.md @@ -0,0 +1,213 @@ +--- +title: BackendV1 +description: API reference for qiskit.providers.BackendV1 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.BackendV1 +--- + +# BackendV1 + + + +`qiskit.providers.BackendV1(configuration, provider=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/backend.py "view source code") + +Bases: [`Backend`](qiskit.providers.Backend "qiskit.providers.backend.Backend"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Abstract class for Backends + +This abstract class is to be used for all Backend objects created by a provider. There are several classes of information contained in a Backend. The first are the attributes of the class itself. These should be used to defined the immutable characteristics of the backend. The `options` attribute of the backend is used to contain the dynamic user configurable options of the backend. It should be used more for runtime options that configure how the backend is used. For example, something like a `shots` field for a backend that runs experiments which would contain an int for how many shots to execute. The `properties` attribute is optionally defined [`BackendProperties`](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") object and is used to return measured properties, or properties of a backend that may change over time. The simplest example of this would be a version string, which will change as a backend is updated, but also could be something like noise parameters for backends that run experiments. + +This first version of the Backend abstract class is written to be mostly backwards compatible with the legacy providers interface. This includes reusing the model objects [`BackendProperties`](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") and [`BackendConfiguration`](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration"). This was done to ease the transition for users and provider maintainers to the new versioned providers. Expect, future versions of this abstract class to change the data model and interface. + +Subclasses of this should override the public method [`run()`](#qiskit.providers.BackendV1.run "qiskit.providers.BackendV1.run") and the internal [`_default_options()`](#qiskit.providers.BackendV1._default_options "qiskit.providers.BackendV1._default_options"): + +### \_default\_options + + + +`abstract classmethod _default_options()` + +Return the default options + +This method will return a [`qiskit.providers.Options`](qiskit.providers.Options "qiskit.providers.Options") subclass object that will be used for the default options. These should be the default parameters to use for the options of the backend. + +**Returns** + +**A options object with** + +default values set + +**Return type** + +[qiskit.providers.Options](qiskit.providers.Options "qiskit.providers.Options") + +Initialize a backend class + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – A backend configuration object for the backend object. +* **provider** ([*qiskit.providers.Provider*](qiskit.providers.Provider "qiskit.providers.Provider")) – Optionally, the provider object that this Backend comes from. +* **fields** – kwargs for the values to use to override the default options. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – if input field not a valid options + +In addition to the public abstract methods, subclasses should also implement the following private methods: + +`abstract classmethod _default_options()` + +Return the default options + +This method will return a [`qiskit.providers.Options`](qiskit.providers.Options "qiskit.providers.Options") subclass object that will be used for the default options. These should be the default parameters to use for the options of the backend. + +**Returns** + +**A options object with** + +default values set + +**Return type** + +[qiskit.providers.Options](qiskit.providers.Options "qiskit.providers.Options") + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.BackendV1.run "qiskit.providers.BackendV1.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return the backend properties. + +**Returns** + +the configuration for the backend. If the backend does not support properties, it returns `None`. + +**Return type** + +[BackendProperties](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`abstract run(run_input, **options)` + +Run on the backend. + +This method returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. For legacy providers migrating to the new versioned providers, provider interface a [`QasmQobj`](qiskit.qobj.QasmQobj "qiskit.qobj.QasmQobj") or [`PulseQobj`](qiskit.qobj.PulseQobj "qiskit.qobj.PulseQobj") objects should probably be supported too (but deprecated) for backwards compatibility. Be sure to update the docstrings of subclasses implementing this method to document that. New provider implementations should not do this though as [`qiskit.qobj`](qobj#module-qiskit.qobj "qiskit.qobj") will be deprecated and removed along with the legacy providers interface. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.BackendV2.md b/docs/api/qiskit/0.46/qiskit.providers.BackendV2.md new file mode 100644 index 00000000000..a7b0012d7b0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.BackendV2.md @@ -0,0 +1,382 @@ +--- +title: BackendV2 +description: API reference for qiskit.providers.BackendV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.BackendV2 +--- + +# BackendV2 + + + +`qiskit.providers.BackendV2(provider=None, name=None, description=None, online_date=None, backend_version=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/backend.py "view source code") + +Bases: [`Backend`](qiskit.providers.Backend "qiskit.providers.backend.Backend"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Abstract class for Backends + +This abstract class is to be used for all Backend objects created by a provider. This version differs from earlier abstract Backend classes in that the configuration attribute no longer exists. Instead, attributes exposing equivalent required immutable properties of the backend device are added. For example `backend.configuration().n_qubits` is accessible from `backend.num_qubits` now. + +The `options` attribute of the backend is used to contain the dynamic user configurable options of the backend. It should be used more for runtime options that configure how the backend is used. For example, something like a `shots` field for a backend that runs experiments which would contain an int for how many shots to execute. + +If migrating a provider from [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") one thing to keep in mind is for backwards compatibility you might need to add a configuration method that will build a [`BackendConfiguration`](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") object and [`BackendProperties`](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") from the attributes defined in this class for backwards compatibility. + +A backend object can optionally contain methods named `get_translation_stage_plugin` and `get_scheduling_stage_plugin`. If these methods are present on a backend object and this object is used for [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`generate_preset_pass_manager()`](transpiler_preset#qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager "qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager") the transpilation process will default to using the output from those methods as the scheduling stage and the translation compilation stage. This enables a backend which has custom requirements for compilation to specify a stage plugin for these stages to enable custom transformation of the circuit to ensure it is runnable on the backend. These hooks are enabled by default and should only be used to enable extra compilation steps if they are **required** to ensure a circuit is executable on the backend or have the expected level of performance. These methods are passed no input arguments and are expected to return a `str` representing the method name which should be a stage plugin (see: [`qiskit.transpiler.preset_passmanagers.plugin`](transpiler_plugins#module-qiskit.transpiler.preset_passmanagers.plugin "qiskit.transpiler.preset_passmanagers.plugin") for more details on plugins). The typical expected use case is for a backend provider to implement a stage plugin for `translation` or `scheduling` that contains the custom compilation passes and then for the hook methods on the backend object to return the plugin name so that [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") will use it by default when targetting the backend. + +Subclasses of this should override the public method [`run()`](#qiskit.providers.BackendV2.run "qiskit.providers.BackendV2.run") and the internal [`_default_options()`](#qiskit.providers.BackendV2._default_options "qiskit.providers.BackendV2._default_options"): + +### \_default\_options + + + +`abstract classmethod _default_options()` + +Return the default options + +This method will return a [`qiskit.providers.Options`](qiskit.providers.Options "qiskit.providers.Options") subclass object that will be used for the default options. These should be the default parameters to use for the options of the backend. + +**Returns** + +**A options object with** + +default values set + +**Return type** + +[qiskit.providers.Options](qiskit.providers.Options "qiskit.providers.Options") + +Initialize a BackendV2 based backend + +**Parameters** + +* **provider** ([*Provider*](qiskit.providers.Provider "qiskit.providers.provider.Provider")) – An optional backwards reference to the [`Provider`](qiskit.providers.Provider "qiskit.providers.Provider") object that the backend is from +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional name for the backend +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional description of the backend +* **online\_date** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")) – An optional datetime the backend was brought online +* **backend\_version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional backend version string. This differs from the [`version`](#qiskit.providers.BackendV2.version "qiskit.providers.BackendV2.version") attribute as [`version`](#qiskit.providers.BackendV2.version "qiskit.providers.BackendV2.version") is for the abstract [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface version of the object while `backend_version` is for versioning the backend itself. +* **fields** – kwargs for the values to use to override the default options. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If a field is specified that’s outside the backend’s options + +## Attributes + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the output signal timestep + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + +The maximum number of circuits (or Pulse schedules) that can be run in a single job. + +If there is no limit this will return None + + + +### meas\_map + +Return the grouping of measurements which are multiplexed + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.BackendV2.run "qiskit.providers.BackendV2.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](#qiskit.providers.BackendV2.version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`abstract run(run_input, **options)` + +Run on the backend. + +This method returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.BackendV2Converter.md b/docs/api/qiskit/0.46/qiskit.providers.BackendV2Converter.md new file mode 100644 index 00000000000..639851eb89f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.BackendV2Converter.md @@ -0,0 +1,333 @@ +--- +title: BackendV2Converter +description: API reference for qiskit.providers.BackendV2Converter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.BackendV2Converter +--- + +# BackendV2Converter + + + +`qiskit.providers.BackendV2Converter(backend, name_mapping=None, add_delay=False, filter_faulty=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/backend_compat.py "view source code") + +Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") + +A converter class that takes a [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") instance and wraps it in a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") interface. + +This class implements the [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") interface and is used to enable common access patterns between [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") and [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2"). This class should only be used if you need a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") and still need compatibility with [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1"). + +When using custom calibrations (or other custom workflows) it is **not** recommended to mutate the `BackendV1` object before applying this converter. For example, in order to convert a `BackendV1` object with a customized `defaults().instruction_schedule_map`, which has a custom calibration for an operation, the operation name must be in `configuration().basis_gates` and `name_mapping` must be supplied for the operation. Otherwise, the operation will be dropped in the resulting `BackendV2` object. + +Instead it is typically better to add custom calibrations **after** applying this converter instead of updating `BackendV1.defaults()` in advance. For example: + +```python +backend_v2 = BackendV2Converter(backend_v1) +backend_v2.target.add_instruction( + custom_gate, {(0, 1): InstructionProperties(calibration=custom_sched)} +) +``` + +Initialize a BackendV2 converter instance based on a BackendV1 instance. + +**Parameters** + +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.BackendV1")) – The input [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.BackendV1") based backend to wrap in a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") interface +* **name\_mapping** (*Optional\[Dict\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any]]*) – An optional dictionary that maps custom gate/operation names in `backend` to an [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") object representing that gate/operation. By default most standard gates names are mapped to the standard gate object from [`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library") this only needs to be specified if the input `backend` defines gates in names outside that set. +* **add\_delay** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to true a [`Delay`](qiskit.circuit.Delay "qiskit.circuit.Delay") operation will be added to the target as a supported operation for all qubits +* **filter\_faulty** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If the [`BackendProperties`](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") object (if present) for `backend` has any qubits or gates flagged as non-operational filter those from the output target. + +## Attributes + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.BackendV2Converter.run "qiskit.providers.BackendV2Converter.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the backend. + +This method returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.Job.md b/docs/api/qiskit/0.46/qiskit.providers.Job.md new file mode 100644 index 00000000000..9942bfc73fd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.Job.md @@ -0,0 +1,28 @@ +--- +title: Job +description: API reference for qiskit.providers.Job +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.Job +--- + +# Job + + + +`qiskit.providers.Job`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/job.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Base common type for all versioned Job abstract classes. + +Note this class should not be inherited from directly, it is intended to be used for type checking. When implementing a provider you should use the versioned abstract classes as the parent class and not this class directly. + +## Attributes + + + +### version + +`= 0` + diff --git a/docs/api/qiskit/0.46/qiskit.providers.JobStatus.md b/docs/api/qiskit/0.46/qiskit.providers.JobStatus.md new file mode 100644 index 00000000000..90d8f04f89c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.JobStatus.md @@ -0,0 +1,62 @@ +--- +title: JobStatus +description: API reference for qiskit.providers.JobStatus +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.JobStatus +--- + +# JobStatus + + + +`qiskit.providers.JobStatus(value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/jobstatus.py "view source code") + +Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.12)") + +Class for job status enumerated type. + +## Attributes + + + +### INITIALIZING + +`= 'job is being initialized'` + + + +### QUEUED + +`= 'job is queued'` + + + +### VALIDATING + +`= 'job is being validated'` + + + +### RUNNING + +`= 'job is actively running'` + + + +### CANCELLED + +`= 'job has been cancelled'` + + + +### DONE + +`= 'job has successfully run'` + + + +### ERROR + +`= 'job incurred error'` + diff --git a/docs/api/qiskit/0.46/qiskit.providers.JobV1.md b/docs/api/qiskit/0.46/qiskit.providers.JobV1.md new file mode 100644 index 00000000000..ae761dec4f1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.JobV1.md @@ -0,0 +1,170 @@ +--- +title: JobV1 +description: API reference for qiskit.providers.JobV1 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.JobV1 +--- + +# JobV1 + + + +`qiskit.providers.JobV1(backend, job_id, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/job.py "view source code") + +Bases: [`Job`](qiskit.providers.Job "qiskit.providers.job.Job"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Class to handle jobs + +This first version of the Backend abstract class is written to be mostly backwards compatible with the legacy providers interface. This was done to ease the transition for users and provider maintainers to the new versioned providers. Expect, future versions of this abstract class to change the data model and interface. + +Initializes the asynchronous job. + +**Parameters** + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – the backend used to run the job. +* **job\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a unique id in the context of the backend used to run the job. +* **kwargs** – Any key value metadata to associate with this job. + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backend + + + +`backend()` + +Return the backend where this job was executed. + +**Return type** + +[*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") + +### cancel + + + +`cancel()` + +Attempt to cancel the job. + +### cancelled + + + +`cancelled()` + +Return whether the job has been cancelled. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### done + + + +`done()` + +Return whether the job has successfully run. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### in\_final\_state + + + +`in_final_state()` + +Return whether the job is in a final job state such as `DONE` or `ERROR`. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### job\_id + + + +`job_id()` + +Return a unique id identifying the job. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### result + + + +`abstract result()` + +Return the results of the job. + +### running + + + +`running()` + +Return whether the job is actively running. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### status + + + +`abstract status()` + +Return the status of the job, among the values of `JobStatus`. + +### submit + + + +`abstract submit()` + +Submit the job to the backend for execution. + +### wait\_for\_final\_state + + + +`wait_for_final_state(timeout=None, wait=5, callback=None)` + +Poll the job status until it progresses to a final state such as `DONE` or `ERROR`. + +**Parameters** + +* **timeout** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Seconds to wait for the job. If `None`, wait indefinitely. + +* **wait** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Seconds between queries. + +* **callback** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – + + Callback function invoked after each query. The following positional arguments are provided to the callback function: + + * job\_id: Job ID + * job\_status: Status of the job from the last query + * job: This BaseJob instance + + Note: different subclass might provide different arguments to the callback function. + +**Raises** + +[**JobTimeoutError**](providers#qiskit.providers.JobTimeoutError "qiskit.providers.JobTimeoutError") – If the job does not reach a final state before the specified timeout. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.Options.md b/docs/api/qiskit/0.46/qiskit.providers.Options.md new file mode 100644 index 00000000000..a2e57a2bf0a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.Options.md @@ -0,0 +1,125 @@ +--- +title: Options +description: API reference for qiskit.providers.Options +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.Options +--- + +# Options + + + +`qiskit.providers.Options(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/options.py "view source code") + +Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "(in Python v3.12)") + +Base options object + +This class is what all backend options are based on. The properties of the class are intended to be all dynamically adjustable so that a user can reconfigure the backend on demand. If a property is immutable to the user (eg something like number of qubits) that should be a configuration of the backend class itself instead of the options. + +Instances of this class behave like dictionaries. Accessing an option with a default value can be done with the get() method: + +```python +>>> options = Options(opt1=1, opt2=2) +>>> options.get("opt1") +1 +>>> options.get("opt3", default="hello") +'hello' +``` + +Key-value pairs for all options can be retrieved using the items() method: + +```python +>>> list(options.items()) +[('opt1', 1), ('opt2', 2)] +``` + +Options can be updated by name: + +```python +>>> options["opt1"] = 3 +>>> options.get("opt1") +3 +``` + +Runtime validators can be registered. See set\_validator. Updates through update\_options and indexing (\_\_setitem\_\_) validate the new value before performing the update and raise ValueError if the new value is invalid. + +```python +>>> options.set_validator("opt1", (1, 5)) +>>> options["opt1"] = 4 +>>> options["opt1"] +4 +>>> options["opt1"] = 10 +Traceback (most recent call last): +... +ValueError: ... +``` + +## Attributes + + + +### validator + +## Methods + +### get + + + +`get(k[, d]) → D[k] if k in D, else d.  d defaults to None.` + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### set\_validator + + + +`set_validator(field, validator_value)` + +Set an optional validator for a field in the options + +Setting a validator enables changes to an options values to be validated for correctness when [`update_options()`](#qiskit.providers.Options.update_options "qiskit.providers.Options.update_options") is called. For example if you have a numeric field like `shots` you can specify a bounds tuple that set an upper and lower bound on the value such as: + +```python +options.set_validator("shots", (1, 4096)) +``` + +In this case whenever the `"shots"` option is updated by the user it will enforce that the value is >=1 and \<=4096. A `ValueError` will be raised if it’s outside those bounds. If a validator is already present for the specified field it will be silently overridden. + +**Parameters** + +* **field** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The field name to set the validator on +* **validator\_value** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)")) – The value to use for the validator depending on the type indicates on how the value for a field is enforced. If a tuple is passed in it must have a length of two and will enforce the min and max value (inclusive) for an integer or float value option. If it’s a list it will list the valid values for a field. If it’s a `type` the validator will just enforce the value is of a certain type. + +**Raises** + +* [**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.12)") – If field is not present in the options object +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the `validator_value` has an invalid value for a given type +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `validator_value` is not a valid type + +### update\_options + + + +`update_options(**fields)` + +Update options with kwargs + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.providers.Provider.md b/docs/api/qiskit/0.46/qiskit.providers.Provider.md new file mode 100644 index 00000000000..5fd5f851fa3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.Provider.md @@ -0,0 +1,28 @@ +--- +title: Provider +description: API reference for qiskit.providers.Provider +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.Provider +--- + +# Provider + + + +`qiskit.providers.Provider`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/provider.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Base common type for all versioned Provider abstract classes. + +Note this class should not be inherited from directly, it is intended to be used for type checking. When implementing a provider you should use the versioned abstract classes as the parent class and not this class directly. + +## Attributes + + + +### version + +`= 0` + diff --git a/docs/api/qiskit/0.46/qiskit.providers.ProviderV1.md b/docs/api/qiskit/0.46/qiskit.providers.ProviderV1.md new file mode 100644 index 00000000000..fe8f1f180f4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.ProviderV1.md @@ -0,0 +1,76 @@ +--- +title: ProviderV1 +description: API reference for qiskit.providers.ProviderV1 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.ProviderV1 +--- + +# ProviderV1 + + + +`qiskit.providers.ProviderV1`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/provider.py "view source code") + +Bases: [`Provider`](qiskit.providers.Provider "qiskit.providers.provider.Provider"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base class for a Backend Provider. + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backends + + + +`abstract backends(name=None, **kwargs)` + +Return a list of backends matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +**a list of Backends that match the filtering** + +criteria. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Backend](qiskit.providers.Backend "qiskit.providers.Backend")] + +### get\_backend + + + +`get_backend(name=None, **kwargs)` + +Return a single backend matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +a backend matching the filtering. + +**Return type** + +[Backend](qiskit.providers.Backend "qiskit.providers.Backend") + +**Raises** + +[**QiskitBackendNotFoundError**](providers#qiskit.providers.QiskitBackendNotFoundError "qiskit.providers.QiskitBackendNotFoundError") – if no backend could be found or more than one backend matches the filtering criteria. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.QubitProperties.md b/docs/api/qiskit/0.46/qiskit.providers.QubitProperties.md new file mode 100644 index 00000000000..18e1359e16f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.QubitProperties.md @@ -0,0 +1,42 @@ +--- +title: QubitProperties +description: API reference for qiskit.providers.QubitProperties +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.QubitProperties +--- + +# QubitProperties + + + +`qiskit.providers.QubitProperties(t1=None, t2=None, frequency=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/backend.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A representation of the properties of a qubit on a backend. + +This class provides the optional properties that a backend can provide for a qubit. These represent the set of qubit properties that Qiskit can currently work with if present. However if your backend provides additional properties of qubits you should subclass this to add additional custom attributes for those custom/additional properties provided by the backend. + +Create a new [`QubitProperties`](#qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object. + +**Parameters** + +* **t1** – The T1 time for a qubit in seconds +* **t2** – The T2 time for a qubit in seconds +* **frequency** – The frequency of a qubit in Hz + +## Attributes + + + +### t1 + + + +### t2 + + + +### frequency + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProvider.md b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProvider.md new file mode 100644 index 00000000000..ca72ea48800 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProvider.md @@ -0,0 +1,76 @@ +--- +title: BasicProvider +description: API reference for qiskit.providers.basic_provider.BasicProvider +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basic_provider.BasicProvider +--- + +# BasicProvider + + + +`qiskit.providers.basic_provider.BasicProvider`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basic_provider/basic_provider.py "view source code") + +Bases: [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.provider.ProviderV1") + +Provider for test simulators. + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backends + + + +`backends(name=None, filters=None, **kwargs)` + +Return a list of backends matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +**a list of Backends that match the filtering** + +criteria. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Backend](qiskit.providers.Backend "qiskit.providers.Backend")] + +### get\_backend + + + +`get_backend(name=None, **kwargs)` + +Return a single backend matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +a backend matching the filtering. + +**Return type** + +[Backend](qiskit.providers.Backend "qiskit.providers.Backend") + +**Raises** + +[**QiskitBackendNotFoundError**](providers#qiskit.providers.QiskitBackendNotFoundError "qiskit.providers.QiskitBackendNotFoundError") – if no backend could be found or more than one backend matches the filtering criteria. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderError.md b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderError.md new file mode 100644 index 00000000000..46cc6dc012c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderError.md @@ -0,0 +1,20 @@ +--- +title: BasicProviderError +description: API reference for qiskit.providers.basic_provider.BasicProviderError +in_page_toc_min_heading_level: 1 +python_api_type: exception +python_api_name: qiskit.providers.basic_provider.BasicProviderError +--- + + + +# qiskit.providers.basic\_provider.BasicProviderError + + + +`qiskit.providers.basic_provider.BasicProviderError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basic_provider/exceptions.py "view source code") + +Base class for errors raised by the Basic Provider. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderJob.md b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderJob.md new file mode 100644 index 00000000000..1a4b9701207 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicProviderJob.md @@ -0,0 +1,184 @@ +--- +title: BasicProviderJob +description: API reference for qiskit.providers.basic_provider.BasicProviderJob +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basic_provider.BasicProviderJob +--- + +# BasicProviderJob + + + +`qiskit.providers.basic_provider.BasicProviderJob(backend, job_id, result)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basic_provider/basic_provider_job.py "view source code") + +Bases: [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.job.JobV1") + +BasicProviderJob class. + +Initializes the asynchronous job. + +**Parameters** + +* **backend** – the backend used to run the job. +* **job\_id** – a unique id in the context of the backend used to run the job. +* **kwargs** – Any key value metadata to associate with this job. + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backend + + + +`backend()` + +Return the instance of the backend used for this job. + +### cancel + + + +`cancel()` + +Attempt to cancel the job. + +### cancelled + + + +`cancelled()` + +Return whether the job has been cancelled. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### done + + + +`done()` + +Return whether the job has successfully run. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### in\_final\_state + + + +`in_final_state()` + +Return whether the job is in a final job state such as `DONE` or `ERROR`. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### job\_id + + + +`job_id()` + +Return a unique id identifying the job. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### result + + + +`result(timeout=None)` + +Get job result . + +**Returns** + +Result object + +**Return type** + +[qiskit.result.Result](qiskit.result.Result "qiskit.result.Result") + +### running + + + +`running()` + +Return whether the job is actively running. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### status + + + +`status()` + +Gets the status of the job by querying the Python’s future + +**Returns** + +The current JobStatus + +**Return type** + +[qiskit.providers.JobStatus](qiskit.providers.JobStatus "qiskit.providers.JobStatus") + +### submit + + + +`submit()` + +Submit the job to the backend for execution. + +**Raises** + +[**JobError**](providers#qiskit.providers.JobError "qiskit.providers.JobError") – if trying to re-submit the job. + +### wait\_for\_final\_state + + + +`wait_for_final_state(timeout=None, wait=5, callback=None)` + +Poll the job status until it progresses to a final state such as `DONE` or `ERROR`. + +**Parameters** + +* **timeout** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Seconds to wait for the job. If `None`, wait indefinitely. + +* **wait** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Seconds between queries. + +* **callback** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – + + Callback function invoked after each query. The following positional arguments are provided to the callback function: + + * job\_id: Job ID + * job\_status: Status of the job from the last query + * job: This BaseJob instance + + Note: different subclass might provide different arguments to the callback function. + +**Raises** + +[**JobTimeoutError**](providers#qiskit.providers.JobTimeoutError "qiskit.providers.JobTimeoutError") – If the job does not reach a final state before the specified timeout. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicSimulator.md b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicSimulator.md new file mode 100644 index 00000000000..14de5eb5476 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basic_provider.BasicSimulator.md @@ -0,0 +1,413 @@ +--- +title: BasicSimulator +description: API reference for qiskit.providers.basic_provider.BasicSimulator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basic_provider.BasicSimulator +--- + +# BasicSimulator + + + +`qiskit.providers.basic_provider.BasicSimulator(provider=None, target=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basic_provider/basic_simulator.py "view source code") + +Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") + +Python implementation of a basic (non-efficient) quantum simulator. + +**Parameters** + +* **provider** ([*Provider*](qiskit.providers.Provider "qiskit.providers.Provider") *| None*) – An optional backwards reference to the [`Provider`](qiskit.providers.Provider "qiskit.providers.Provider") object that the backend is from. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target") *| None*) – An optional target to configure the simulator. +* **fields** – kwargs for the values to use to override the default options. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If a field is specified that’s outside the backend’s options. + +## Attributes + + + +### MAX\_QUBITS\_MEMORY + +`= 24` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the output signal timestep + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.basic_provider.BasicSimulator.run "qiskit.providers.basic_provider.BasicSimulator.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### configuration + + + +`configuration()` + +Return the simulator backend configuration. + +**Returns** + +The configuration for the backend. + +**Return type** + +[*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.backendconfiguration.BackendConfiguration") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **backend_options)` + +Run on the backend. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – payload of the experiment +* **backend\_options** – backend options + +**Returns** + +derived from BaseJob + +**Return type** + +[BasicProviderJob](qiskit.providers.basic_provider.BasicProviderJob "qiskit.providers.basic_provider.BasicProviderJob") + +**Additional Information:** + +**backend\_options: Is a dict of options for the backend. It may contain** + +* “initial\_statevector”: vector\_like + +The “initial\_statevector” option specifies a custom initial initial statevector for the simulator to be used instead of the all zero state. This size of this vector must be correct for the number of qubits in `run_input` parameter. + +Example: + +```python +backend_options = { + "initial_statevector": np.array([1, 0, 0, 1j]) / np.sqrt(2), +} +``` + +### run\_experiment + + + +`run_experiment(experiment)` + +Run an experiment (circuit) and return a single experiment result. + +**Parameters** + +**experiment** ([*QasmQobjExperiment*](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.qasm_qobj.QasmQobjExperiment")) – experiment from qobj experiments list + +**Returns** + +A result dictionary which looks something like: + +```python +{ +"name": name of this experiment (obtained from qobj.experiment header) +"seed": random seed used for simulation +"shots": number of shots used in the simulation +"data": + { + "counts": {'0x9: 5, ...}, + "memory": ['0x9', '0xF', '0x1D', ..., '0x9'] + }, +"status": status string for the simulation +"success": boolean +"time_taken": simulation time of this single experiment +} +``` + +**Raises** + +[**BasicProviderError**](qiskit.providers.basic_provider.BasicProviderError "qiskit.providers.basic_provider.BasicProviderError") – if an error occurred. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), …] + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerError.md b/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerError.md new file mode 100644 index 00000000000..0e74ac66148 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerError.md @@ -0,0 +1,24 @@ +--- +title: BasicAerError +description: API reference for qiskit.providers.basicaer.BasicAerError +in_page_toc_min_heading_level: 1 +python_api_type: exception +python_api_name: qiskit.providers.basicaer.BasicAerError +--- + + + +# qiskit.providers.basicaer.BasicAerError + + + +`qiskit.providers.basicaer.BasicAerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basicaer/exceptions.py "view source code") + +Base class for errors raised by Basic Aer. + +Set the error message. + + + The class `qiskit.providers.basicaer.exceptions.BasicAerError` is deprecated as of qiskit 0.46.0. It will be removed in Qiskit 1.0.0. The qiskit.providers.basicaer module has been superseded by qiskit.providers.basic\_provider. Use the new qiskit.providers.basic\_provider.BasicProviderError class instead. + + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerJob.md b/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerJob.md new file mode 100644 index 00000000000..f8372e79924 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerJob.md @@ -0,0 +1,180 @@ +--- +title: BasicAerJob +description: API reference for qiskit.providers.basicaer.BasicAerJob +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basicaer.BasicAerJob +--- + +# BasicAerJob + + + +`qiskit.providers.basicaer.BasicAerJob(backend, job_id, result)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basicaer/basicaerjob.py "view source code") + +Bases: [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.job.JobV1") + +BasicAerJob class. + + + The class `qiskit.providers.basicaer.basicaerjob.BasicAerJob` is deprecated as of qiskit 0.46.0. It will be removed in Qiskit 1.0.0. The qiskit.providers.basicaer module has been superseded by qiskit.providers.basic\_provider, and all its classes have been renamed to follow a new naming convention. Use the new qiskit.providers.basic\_provider.BasicProviderJob class instead. + + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backend + + + +`backend()` + +Return the instance of the backend used for this job. + +### cancel + + + +`cancel()` + +Attempt to cancel the job. + +### cancelled + + + +`cancelled()` + +Return whether the job has been cancelled. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### done + + + +`done()` + +Return whether the job has successfully run. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### in\_final\_state + + + +`in_final_state()` + +Return whether the job is in a final job state such as `DONE` or `ERROR`. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### job\_id + + + +`job_id()` + +Return a unique id identifying the job. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### result + + + +`result(timeout=None)` + +Get job result . + +**Returns** + +Result object + +**Return type** + +[qiskit.result.Result](qiskit.result.Result "qiskit.result.Result") + +### running + + + +`running()` + +Return whether the job is actively running. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### status + + + +`status()` + +Gets the status of the job by querying the Python’s future + +**Returns** + +The current JobStatus + +**Return type** + +[qiskit.providers.JobStatus](qiskit.providers.JobStatus "qiskit.providers.JobStatus") + +### submit + + + +`submit()` + +Submit the job to the backend for execution. + +**Raises** + +[**JobError**](providers#qiskit.providers.JobError "qiskit.providers.JobError") – if trying to re-submit the job. + +### wait\_for\_final\_state + + + +`wait_for_final_state(timeout=None, wait=5, callback=None)` + +Poll the job status until it progresses to a final state such as `DONE` or `ERROR`. + +**Parameters** + +* **timeout** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Seconds to wait for the job. If `None`, wait indefinitely. + +* **wait** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Seconds between queries. + +* **callback** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – + + Callback function invoked after each query. The following positional arguments are provided to the callback function: + + * job\_id: Job ID + * job\_status: Status of the job from the last query + * job: This BaseJob instance + + Note: different subclass might provide different arguments to the callback function. + +**Raises** + +[**JobTimeoutError**](providers#qiskit.providers.JobTimeoutError "qiskit.providers.JobTimeoutError") – If the job does not reach a final state before the specified timeout. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerProvider.md b/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerProvider.md new file mode 100644 index 00000000000..1bdd93c0dd3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basicaer.BasicAerProvider.md @@ -0,0 +1,80 @@ +--- +title: BasicAerProvider +description: API reference for qiskit.providers.basicaer.BasicAerProvider +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basicaer.BasicAerProvider +--- + +# BasicAerProvider + + + +`qiskit.providers.basicaer.BasicAerProvider`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basicaer/basicaerprovider.py "view source code") + +Bases: [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.provider.ProviderV1") + +Provider for Basic Aer backends. + + + The class `qiskit.providers.basicaer.basicaerprovider.BasicAerProvider` is deprecated as of qiskit 0.46.0. It will be removed in Qiskit 1.0.0. The qiskit.providers.basicaer module has been superseded by qiskit.providers.basic\_provider, and all its classes have been renamed to follow a new naming convention. Use the new qiskit.providers.basic\_provider.BasicProvider class instead. + + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backends + + + +`backends(name=None, filters=None, **kwargs)` + +Return a list of backends matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +**a list of Backends that match the filtering** + +criteria. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Backend](qiskit.providers.Backend "qiskit.providers.Backend")] + +### get\_backend + + + +`get_backend(name=None, **kwargs)` + +Return a single backend matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +a backend matching the filtering. + +**Return type** + +[Backend](qiskit.providers.Backend "qiskit.providers.Backend") + +**Raises** + +[**QiskitBackendNotFoundError**](providers#qiskit.providers.QiskitBackendNotFoundError "qiskit.providers.QiskitBackendNotFoundError") – if no backend could be found or more than one backend matches the filtering criteria. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basicaer.QasmSimulatorPy.md b/docs/api/qiskit/0.46/qiskit.providers.basicaer.QasmSimulatorPy.md new file mode 100644 index 00000000000..6cf79e8f056 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basicaer.QasmSimulatorPy.md @@ -0,0 +1,243 @@ +--- +title: QasmSimulatorPy +description: API reference for qiskit.providers.basicaer.QasmSimulatorPy +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basicaer.QasmSimulatorPy +--- + +# QasmSimulatorPy + + + +`qiskit.providers.basicaer.QasmSimulatorPy(configuration=None, provider=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basicaer/qasm_simulator.py "view source code") + +Bases: [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.backend.BackendV1") + +Python implementation of an OpenQASM 2 simulator. + + + The class `qiskit.providers.basicaer.qasm_simulator.QasmSimulatorPy` is deprecated as of qiskit 0.46.0. It will be removed in Qiskit 1.0.0. The qiskit.providers.basicaer module has been superseded by qiskit.providers.basic\_provider. Use the new qiskit.providers.basic\_provider.BasicSimulator class instead. + + +## Attributes + + + +### DEFAULT\_CONFIGURATION = \{'backend\_name' + +`= {'backend_name':` + +`= {'backend_name': 'qasm_simulator', 'backend_version': '2.1.0', 'basis_gates': ['h', 'u', 'p', 'u1', 'u2', 'u3', 'rz', 'sx', 'x', 'cx', 'id', 'unitary'], 'conditional': True, 'coupling_map': None, 'description': 'A python simulator for qasm experiments', 'gates': [{'name': 'h', 'parameters': [], 'qasm_def': 'gate h q { U(pi/2,0,pi) q; }'}, {'name': 'p', 'parameters': ['lambda'], 'qasm_def': 'gate p(lambda) q { U(0,0,lambda) q; }'}, {'name': 'u', 'parameters': ['theta', 'phi', 'lambda'], 'qasm_def': 'gate u(theta,phi,lambda) q { U(theta,phi,lambda) q; }'}, {'name': 'u1', 'parameters': ['lambda'], 'qasm_def': 'gate u1(lambda) q { U(0,0,lambda) q; }'}, {'name': 'u2', 'parameters': ['phi', 'lambda'], 'qasm_def': 'gate u2(phi,lambda) q { U(pi/2,phi,lambda) q; }'}, {'name': 'u3', 'parameters': ['theta', 'phi', 'lambda'], 'qasm_def': 'gate u3(theta,phi,lambda) q { U(theta,phi,lambda) q; }'}, {'name': 'rz', 'parameters': ['phi'], 'qasm_def': 'gate rz(phi) q { U(0,0,phi) q; }'}, {'name': 'sx', 'parameters': [], 'qasm_def': 'gate sx(phi) q { U(pi/2,7*pi/2,pi/2) q; }'}, {'name': 'x', 'parameters': [], 'qasm_def': 'gate x q { U(pi,7*pi/2,pi/2) q; }'}, {'name': 'cx', 'parameters': [], 'qasm_def': 'gate cx c,t { CX c,t; }'}, {'name': 'id', 'parameters': [], 'qasm_def': 'gate id a { U(0,0,0) a; }'}, {'name': 'unitary', 'parameters': ['matrix'], 'qasm_def': 'unitary(matrix) q1, q2,...'}], 'local': True, 'max_shots': 0, 'memory': True, 'n_qubits': 24, 'open_pulse': False, 'simulator': True, 'url': 'https://github.com/Qiskit/qiskit-terra'}` + + + +### DEFAULT\_OPTIONS = \{'chop\_threshold' + +`= {'chop_threshold':` + +`= {'chop_threshold': 1e-15, 'initial_statevector': None}` + + + +### MAX\_QUBITS\_MEMORY + +`= 29` + + + +### SHOW\_FINAL\_STATE + +`= False` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.basicaer.QasmSimulatorPy.run "qiskit.providers.basicaer.QasmSimulatorPy.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return the backend properties. + +**Returns** + +the configuration for the backend. If the backend does not support properties, it returns `None`. + +**Return type** + +[BackendProperties](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **backend_options)` + +Run on the backend. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – payload of the experiment +* **backend\_options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – backend options + +**Returns** + +derived from BaseJob + +**Return type** + +[BasicAerJob](qiskit.providers.basicaer.BasicAerJob "qiskit.providers.basicaer.BasicAerJob") + +**Additional Information:** + +**backend\_options: Is a dict of options for the backend. It may contain** + +* “initial\_statevector”: vector\_like + +The “initial\_statevector” option specifies a custom initial initial statevector for the simulator to be used instead of the all zero state. This size of this vector must be correct for the number of qubits in `run_input` parameter. + +Example: + +```python +backend_options = { + "initial_statevector": np.array([1, 0, 0, 1j]) / np.sqrt(2), +} +``` + +### run\_experiment + + + +`run_experiment(experiment)` + +Run an experiment (circuit) and return a single experiment result. + +**Parameters** + +**experiment** ([*QasmQobjExperiment*](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment")) – experiment from qobj experiments list + +**Returns** + +A result dictionary which looks something like: + +```python +{ +"name": name of this experiment (obtained from qobj.experiment header) +"seed": random seed used for simulation +"shots": number of shots used in the simulation +"data": + { + "counts": {'0x9: 5, ...}, + "memory": ['0x9', '0xF', '0x1D', ..., '0x9'] + }, +"status": status string for the simulation +"success": boolean +"time_taken": simulation time of this single experiment +} +``` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**BasicAerError**](qiskit.providers.basicaer.BasicAerError "qiskit.providers.basicaer.BasicAerError") – if an error occurred. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basicaer.StatevectorSimulatorPy.md b/docs/api/qiskit/0.46/qiskit.providers.basicaer.StatevectorSimulatorPy.md new file mode 100644 index 00000000000..d1c39d8fbbf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basicaer.StatevectorSimulatorPy.md @@ -0,0 +1,243 @@ +--- +title: StatevectorSimulatorPy +description: API reference for qiskit.providers.basicaer.StatevectorSimulatorPy +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basicaer.StatevectorSimulatorPy +--- + +# StatevectorSimulatorPy + + + +`qiskit.providers.basicaer.StatevectorSimulatorPy(configuration=None, provider=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basicaer/statevector_simulator.py "view source code") + +Bases: [`QasmSimulatorPy`](qiskit.providers.basicaer.QasmSimulatorPy "qiskit.providers.basicaer.qasm_simulator.QasmSimulatorPy") + +Python statevector simulator. + + + The class `qiskit.providers.basicaer.statevector_simulator.StatevectorSimulatorPy` is deprecated as of qiskit 0.46.0. It will be removed in Qiskit 1.0.0. The qiskit.providers.basicaer module has been superseded by qiskit.providers.basic\_provider. The new module has no replacement for this class. Use the qiskit.quantum\_info.Statevector class instead. + + +## Attributes + + + +### DEFAULT\_CONFIGURATION = \{'backend\_name' + +`= {'backend_name':` + +`= {'backend_name': 'statevector_simulator', 'backend_version': '1.1.0', 'basis_gates': ['u1', 'u2', 'u3', 'rz', 'sx', 'x', 'cx', 'id', 'unitary'], 'conditional': True, 'coupling_map': None, 'description': 'A Python statevector simulator for qobj files', 'gates': [{'name': 'u1', 'parameters': ['lambda'], 'qasm_def': 'gate u1(lambda) q { U(0,0,lambda) q; }'}, {'name': 'u2', 'parameters': ['phi', 'lambda'], 'qasm_def': 'gate u2(phi,lambda) q { U(pi/2,phi,lambda) q; }'}, {'name': 'u3', 'parameters': ['theta', 'phi', 'lambda'], 'qasm_def': 'gate u3(theta,phi,lambda) q { U(theta,phi,lambda) q; }'}, {'name': 'rz', 'parameters': ['phi'], 'qasm_def': 'gate rz(phi) q { U(0,0,phi) q; }'}, {'name': 'sx', 'parameters': [], 'qasm_def': 'gate sx(phi) q { U(pi/2,7*pi/2,pi/2) q; }'}, {'name': 'x', 'parameters': [], 'qasm_def': 'gate x q { U(pi,7*pi/2,pi/2) q; }'}, {'name': 'cx', 'parameters': [], 'qasm_def': 'gate cx c,t { CX c,t; }'}, {'name': 'id', 'parameters': [], 'qasm_def': 'gate id a { U(0,0,0) a; }'}, {'name': 'unitary', 'parameters': ['matrix'], 'qasm_def': 'unitary(matrix) q1, q2,...'}], 'local': True, 'max_shots': 0, 'memory': True, 'n_qubits': 24, 'open_pulse': False, 'simulator': True, 'url': 'https://github.com/Qiskit/qiskit-terra'}` + + + +### DEFAULT\_OPTIONS = \{'chop\_threshold' + +`= {'chop_threshold':` + +`= {'chop_threshold': 1e-15, 'initial_statevector': None}` + + + +### MAX\_QUBITS\_MEMORY + +`= 29` + + + +### SHOW\_FINAL\_STATE + +`= True` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.basicaer.StatevectorSimulatorPy.run "qiskit.providers.basicaer.StatevectorSimulatorPy.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return the backend properties. + +**Returns** + +the configuration for the backend. If the backend does not support properties, it returns `None`. + +**Return type** + +[BackendProperties](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **backend_options)` + +Run on the backend. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – payload of the experiment +* **backend\_options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – backend options + +**Returns** + +derived from BaseJob + +**Return type** + +[BasicAerJob](qiskit.providers.basicaer.BasicAerJob "qiskit.providers.basicaer.BasicAerJob") + +**Additional Information:** + +**backend\_options: Is a dict of options for the backend. It may contain** + +* “initial\_statevector”: vector\_like + +The “initial\_statevector” option specifies a custom initial initial statevector for the simulator to be used instead of the all zero state. This size of this vector must be correct for the number of qubits in `run_input` parameter. + +Example: + +```python +backend_options = { + "initial_statevector": np.array([1, 0, 0, 1j]) / np.sqrt(2), +} +``` + +### run\_experiment + + + +`run_experiment(experiment)` + +Run an experiment (circuit) and return a single experiment result. + +**Parameters** + +**experiment** ([*QasmQobjExperiment*](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment")) – experiment from qobj experiments list + +**Returns** + +A result dictionary which looks something like: + +```python +{ +"name": name of this experiment (obtained from qobj.experiment header) +"seed": random seed used for simulation +"shots": number of shots used in the simulation +"data": + { + "counts": {'0x9: 5, ...}, + "memory": ['0x9', '0xF', '0x1D', ..., '0x9'] + }, +"status": status string for the simulation +"success": boolean +"time_taken": simulation time of this single experiment +} +``` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**BasicAerError**](qiskit.providers.basicaer.BasicAerError "qiskit.providers.basicaer.BasicAerError") – if an error occurred. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.basicaer.UnitarySimulatorPy.md b/docs/api/qiskit/0.46/qiskit.providers.basicaer.UnitarySimulatorPy.md new file mode 100644 index 00000000000..6b81a8dfa67 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.basicaer.UnitarySimulatorPy.md @@ -0,0 +1,252 @@ +--- +title: UnitarySimulatorPy +description: API reference for qiskit.providers.basicaer.UnitarySimulatorPy +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.basicaer.UnitarySimulatorPy +--- + +# UnitarySimulatorPy + + + +`qiskit.providers.basicaer.UnitarySimulatorPy(configuration=None, provider=None, **fields)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/basicaer/unitary_simulator.py "view source code") + +Bases: [`BackendV1`](qiskit.providers.BackendV1 "qiskit.providers.backend.BackendV1") + +Python implementation of a unitary simulator. + + + The class `qiskit.providers.basicaer.unitary_simulator.UnitarySimulatorPy` is deprecated as of qiskit 0.46.0. It will be removed in Qiskit 1.0.0. The qiskit.providers.basicaer module has been superseded by qiskit.providers.basic\_provider. The new module has no replacement for this class. Use the qiskit.quantum\_info.Operator class instead. + + +## Attributes + + + +### DEFAULT\_CONFIGURATION = \{'backend\_name' + +`= {'backend_name':` + +`= {'backend_name': 'unitary_simulator', 'backend_version': '1.1.0', 'basis_gates': ['u1', 'u2', 'u3', 'rz', 'sx', 'x', 'cx', 'id', 'unitary'], 'conditional': False, 'coupling_map': None, 'description': 'A python simulator for unitary matrix corresponding to a circuit', 'gates': [{'name': 'u1', 'parameters': ['lambda'], 'qasm_def': 'gate u1(lambda) q { U(0,0,lambda) q; }'}, {'name': 'u2', 'parameters': ['phi', 'lambda'], 'qasm_def': 'gate u2(phi,lambda) q { U(pi/2,phi,lambda) q; }'}, {'name': 'u3', 'parameters': ['theta', 'phi', 'lambda'], 'qasm_def': 'gate u3(theta,phi,lambda) q { U(theta,phi,lambda) q; }'}, {'name': 'rz', 'parameters': ['phi'], 'qasm_def': 'gate rz(phi) q { U(0,0,phi) q; }'}, {'name': 'sx', 'parameters': [], 'qasm_def': 'gate sx(phi) q { U(pi/2,7*pi/2,pi/2) q; }'}, {'name': 'x', 'parameters': [], 'qasm_def': 'gate x q { U(pi,7*pi/2,pi/2) q; }'}, {'name': 'cx', 'parameters': [], 'qasm_def': 'gate cx c,t { CX c,t; }'}, {'name': 'id', 'parameters': [], 'qasm_def': 'gate id a { U(0,0,0) a; }'}, {'name': 'unitary', 'parameters': ['matrix'], 'qasm_def': 'unitary(matrix) q1, q2,...'}], 'local': True, 'max_shots': 0, 'memory': False, 'n_qubits': 14, 'open_pulse': False, 'simulator': True, 'url': 'https://github.com/Qiskit/qiskit-terra'}` + + + +### DEFAULT\_OPTIONS = \{'chop\_threshold' + +`= {'chop_threshold':` + +`= {'chop_threshold': 1e-15, 'initial_unitary': None}` + + + +### MAX\_QUBITS\_MEMORY + +`= 14` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.basicaer.UnitarySimulatorPy.run "qiskit.providers.basicaer.UnitarySimulatorPy.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return the backend properties. + +**Returns** + +the configuration for the backend. If the backend does not support properties, it returns `None`. + +**Return type** + +[BackendProperties](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **backend_options)` + +Run experiments in run\_input asynchronously. + + + Using a QasmQobj for the first argument to UnitarySimulatorPy.run() is deprecated as of qiskit 0.46.0. It will be removed no earlier than 3 months after the release date. + + +**Parameters** + +* **run\_input** (*Qobj,* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*,* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – payload of the experiment +* **backend\_options** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – backend options + +**Returns** + +derived from BaseJob + +**Return type** + +[BasicAerJob](qiskit.providers.basicaer.BasicAerJob "qiskit.providers.basicaer.BasicAerJob") + +Additional Information: + +```python +backend_options: Is a dict of options for the backend. It may contain + * "initial_unitary": matrix_like + * "chop_threshold": double + +The "initial_unitary" option specifies a custom initial unitary +matrix for the simulator to be used instead of the identity +matrix. This size of this matrix must be correct for the number +of qubits in all experiments in the run_input. + +The "chop_threshold" option specifies a truncation value for +setting small values to zero in the output unitary. The default +value is 1e-15. + +Example:: + + backend_options = { + "initial_unitary": np.array([[1, 0, 0, 0], + [0, 0, 0, 1], + [0, 0, 1, 0], + [0, 1, 0, 0]]) + "chop_threshold": 1e-15 + } +``` + +### run\_experiment + + + +`run_experiment(experiment)` + +Run an experiment (circuit) and return a single experiment result. + +**Parameters** + +**experiment** ([*QasmQobjExperiment*](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment")) – experiment from qobj experiments list + +**Returns** + +A result dictionary which looks something like: + +```python +{ +"name": name of this experiment (obtained from qobj.experiment header) +"seed": random seed used for simulation +"shots": number of shots used in the simulation +"data": + { + "unitary": [[[0.0, 0.0], [1.0, 0.0]], + [[1.0, 0.0], [0.0, 0.0]]] + }, +"status": status string for the simulation +"success": boolean +"time taken": simulation time of this single experiment +} +``` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**BasicAerError**](qiskit.providers.basicaer.BasicAerError "qiskit.providers.basicaer.BasicAerError") – if the number of qubits in the circuit is greater than 24. Note that the practical qubit limit is much lower than 24. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.convert_to_target.md b/docs/api/qiskit/0.46/qiskit.providers.convert_to_target.md new file mode 100644 index 00000000000..4aa5d43ca88 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.convert_to_target.md @@ -0,0 +1,26 @@ +--- +title: convert_to_target +description: API reference for qiskit.providers.convert_to_target +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.providers.convert_to_target +--- + + + +# qiskit.providers.convert\_to\_target + + + +`qiskit.providers.convert_to_target(configuration, properties=None, defaults=None, custom_name_mapping=None, add_delay=False, filter_faulty=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/backend_compat.py "view source code") + +Uses configuration, properties and pulse defaults to construct and return Target class. + +In order to convert with a `defaults.instruction_schedule_map`, which has a custom calibration for an operation, the operation name must be in `configuration.basis_gates` and `custom_name_mapping` must be supplied for the operation. Otherwise, the operation will be dropped in the resulting `Target` object. + +That suggests it is recommended to add custom calibrations **after** creating a target with this function instead of adding them to `defaults` in advance. For example: + +```python +target.add_instruction(custom_gate, {(0, 1): InstructionProperties(calibration=custom_sched)}) +``` + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.ConfigurableFakeBackend.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.ConfigurableFakeBackend.md new file mode 100644 index 00000000000..2b03224f790 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.ConfigurableFakeBackend.md @@ -0,0 +1,164 @@ +--- +title: ConfigurableFakeBackend +description: API reference for qiskit.providers.fake_provider.ConfigurableFakeBackend +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.ConfigurableFakeBackend +--- + +# ConfigurableFakeBackend + + + +`qiskit.providers.fake_provider.ConfigurableFakeBackend(name, n_qubits, version=None, coupling_map=None, basis_gates=None, qubit_t1=None, qubit_t2=None, qubit_frequency=None, qubit_readout_error=None, single_qubit_gates=None, dt=None, std=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/utils/configurable_backend.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +Configurable backend. + +Creates backend based on provided configuration. + + + The class `qiskit.providers.fake_provider.utils.configurable_backend.ConfigurableFakeBackend` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. Use a suitable FakeBackend instead. + + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of the backend. +* **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of qubits in the backend. +* **version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Version of the fake backend. +* **coupling\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – Coupling map. +* **basis\_gates** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – Basis gates of the backend. +* **qubit\_t1** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Longitudinal coherence times. +* **qubit\_t2** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Transverse coherence times. +* **qubit\_frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Frequency of qubits. +* **qubit\_readout\_error** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Readout error of qubits. +* **single\_qubit\_gates** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – List of single qubit gates for backend properties. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Discretization of the input time sequences. +* **std** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Standard deviation of the generated distributions. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Random seed. + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.ConfigurableFakeBackend.run "qiskit.providers.fake_provider.ConfigurableFakeBackend.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Return backend defaults. + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return backend properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.Fake1Q.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.Fake1Q.md new file mode 100644 index 00000000000..9ef881f6829 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.Fake1Q.md @@ -0,0 +1,136 @@ +--- +title: Fake1Q +description: API reference for qiskit.providers.fake_provider.Fake1Q +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.Fake1Q +--- + +# Fake1Q + + + +`qiskit.providers.fake_provider.Fake1Q`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_1q.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake 1Q backend. + +0 + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.Fake1Q.run "qiskit.providers.fake_provider.Fake1Q.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return backend properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmaden.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmaden.md new file mode 100644 index 00000000000..1385b9c5aab --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmaden.md @@ -0,0 +1,175 @@ +--- +title: FakeAlmaden +description: API reference for qiskit.providers.fake_provider.FakeAlmaden +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeAlmaden +--- + +# FakeAlmaden + + + +`qiskit.providers.fake_provider.FakeAlmaden`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/almaden/fake_almaden.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake Almaden backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_almaden'` + + + +### conf\_filename + +`= 'conf_almaden.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/almaden'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeAlmaden.run "qiskit.providers.fake_provider.FakeAlmaden.run") method. + + + +### props\_filename + +`= 'props_almaden.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmadenV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmadenV2.md new file mode 100644 index 00000000000..17f74a5a3f1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAlmadenV2.md @@ -0,0 +1,361 @@ +--- +title: FakeAlmadenV2 +description: API reference for qiskit.providers.fake_provider.FakeAlmadenV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeAlmadenV2 +--- + +# FakeAlmadenV2 + + + +`qiskit.providers.fake_provider.FakeAlmadenV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/almaden/fake_almaden.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Almaden V2 backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_almaden'` + + + +### conf\_filename + +`= 'conf_almaden.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/almaden'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeAlmadenV2.run "qiskit.providers.fake_provider.FakeAlmadenV2.run") method. + + + +### props\_filename + +`= 'props_almaden.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonk.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonk.md new file mode 100644 index 00000000000..70431733e45 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonk.md @@ -0,0 +1,183 @@ +--- +title: FakeArmonk +description: API reference for qiskit.providers.fake_provider.FakeArmonk +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeArmonk +--- + +# FakeArmonk + + + +`qiskit.providers.fake_provider.FakeArmonk`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/armonk/fake_armonk.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 1 qubit backend. + +```python +0 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_armonk'` + + + +### conf\_filename + +`= 'conf_armonk.json'` + + + +### defs\_filename + +`= 'defs_armonk.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/armonk'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeArmonk.run "qiskit.providers.fake_provider.FakeArmonk.run") method. + + + +### props\_filename + +`= 'props_armonk.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonkV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonkV2.md new file mode 100644 index 00000000000..1f44ae9d5d9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeArmonkV2.md @@ -0,0 +1,355 @@ +--- +title: FakeArmonkV2 +description: API reference for qiskit.providers.fake_provider.FakeArmonkV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeArmonkV2 +--- + +# FakeArmonkV2 + + + +`qiskit.providers.fake_provider.FakeArmonkV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/armonk/fake_armonk.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 1 qubit backend. + +```python +0 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_armonk'` + + + +### conf\_filename + +`= 'conf_armonk.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_armonk.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/armonk'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeArmonkV2.run "qiskit.providers.fake_provider.FakeArmonkV2.run") method. + + + +### props\_filename + +`= 'props_armonk.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthens.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthens.md new file mode 100644 index 00000000000..59d36f40174 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthens.md @@ -0,0 +1,179 @@ +--- +title: FakeAthens +description: API reference for qiskit.providers.fake_provider.FakeAthens +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeAthens +--- + +# FakeAthens + + + +`qiskit.providers.fake_provider.FakeAthens`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/athens/fake_athens.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_athens'` + + + +### conf\_filename + +`= 'conf_athens.json'` + + + +### defs\_filename + +`= 'defs_athens.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/athens'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeAthens.run "qiskit.providers.fake_provider.FakeAthens.run") method. + + + +### props\_filename + +`= 'props_athens.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthensV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthensV2.md new file mode 100644 index 00000000000..964b921ba2f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAthensV2.md @@ -0,0 +1,351 @@ +--- +title: FakeAthensV2 +description: API reference for qiskit.providers.fake_provider.FakeAthensV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeAthensV2 +--- + +# FakeAthensV2 + + + +`qiskit.providers.fake_provider.FakeAthensV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/athens/fake_athens.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_athens'` + + + +### conf\_filename + +`= 'conf_athens.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_athens.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/athens'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeAthensV2.run "qiskit.providers.fake_provider.FakeAthensV2.run") method. + + + +### props\_filename + +`= 'props_athens.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAuckland.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAuckland.md new file mode 100644 index 00000000000..1e13aa93a2b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeAuckland.md @@ -0,0 +1,351 @@ +--- +title: FakeAuckland +description: API reference for qiskit.providers.fake_provider.FakeAuckland +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeAuckland +--- + +# FakeAuckland + + + +`qiskit.providers.fake_provider.FakeAuckland`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/auckland/fake_auckland.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_auckland'` + + + +### conf\_filename + +`= 'conf_auckland.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_auckland.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/auckland'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeAuckland.run "qiskit.providers.fake_provider.FakeAuckland.run") method. + + + +### props\_filename + +`= 'props_auckland.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackend5QV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackend5QV2.md new file mode 100644 index 00000000000..93692e95f3d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackend5QV2.md @@ -0,0 +1,331 @@ +--- +title: FakeBackend5QV2 +description: API reference for qiskit.providers.fake_provider.FakeBackend5QV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBackend5QV2 +--- + +# FakeBackend5QV2 + + + +`qiskit.providers.fake_provider.FakeBackend5QV2(bidirectional=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_backend_v2.py "view source code") + +Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") + +A mock backend that doesn’t implement run() to test compatibility with Terra internals. + + + The class `qiskit.providers.fake_provider.fake_backend_v2.FakeBackend5QV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. Use the qiskit.providers.basic\_provider.GenericBackendV2 class instead. + + +## Attributes + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the output signal timestep + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBackend5QV2.run "qiskit.providers.fake_provider.FakeBackend5QV2.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the backend. + +This method returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackendV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackendV2.md new file mode 100644 index 00000000000..90dd892bc01 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBackendV2.md @@ -0,0 +1,331 @@ +--- +title: FakeBackendV2 +description: API reference for qiskit.providers.fake_provider.FakeBackendV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBackendV2 +--- + +# FakeBackendV2 + + + +`qiskit.providers.fake_provider.FakeBackendV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_backend_v2.py "view source code") + +Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") + +A mock backend that doesn’t implement run() to test compatibility with Terra internals. + + + The class `qiskit.providers.fake_provider.fake_backend_v2.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. Use the qiskit.providers.basic\_provider.GenericBackendV2 class instead. + + +## Attributes + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the output signal timestep + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBackendV2.run "qiskit.providers.fake_provider.FakeBackendV2.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the backend. + +This method returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelem.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelem.md new file mode 100644 index 00000000000..9e078dab5cd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelem.md @@ -0,0 +1,179 @@ +--- +title: FakeBelem +description: API reference for qiskit.providers.fake_provider.FakeBelem +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBelem +--- + +# FakeBelem + + + +`qiskit.providers.fake_provider.FakeBelem`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/belem/fake_belem.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_belem'` + + + +### conf\_filename + +`= 'conf_belem.json'` + + + +### defs\_filename + +`= 'defs_belem.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/belem'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBelem.run "qiskit.providers.fake_provider.FakeBelem.run") method. + + + +### props\_filename + +`= 'props_belem.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelemV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelemV2.md new file mode 100644 index 00000000000..698ed317683 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBelemV2.md @@ -0,0 +1,351 @@ +--- +title: FakeBelemV2 +description: API reference for qiskit.providers.fake_provider.FakeBelemV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBelemV2 +--- + +# FakeBelemV2 + + + +`qiskit.providers.fake_provider.FakeBelemV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/belem/fake_belem.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_belem'` + + + +### conf\_filename + +`= 'conf_belem.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_belem.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/belem'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBelemV2.run "qiskit.providers.fake_provider.FakeBelemV2.run") method. + + + +### props\_filename + +`= 'props_belem.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingen.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingen.md new file mode 100644 index 00000000000..cc48009f431 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingen.md @@ -0,0 +1,189 @@ +--- +title: FakeBoeblingen +description: API reference for qiskit.providers.fake_provider.FakeBoeblingen +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBoeblingen +--- + +# FakeBoeblingen + + + +`qiskit.providers.fake_provider.FakeBoeblingen`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/boeblingen/fake_boeblingen.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake Boeblingen backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_boeblingen'` + + + +### conf\_filename + +`= 'conf_boeblingen.json'` + + + +### defs\_filename + +`= 'defs_boeblingen.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/boeblingen'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBoeblingen.run "qiskit.providers.fake_provider.FakeBoeblingen.run") method. + + + +### props\_filename + +`= 'props_boeblingen.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingenV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingenV2.md new file mode 100644 index 00000000000..a48f4755d12 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBoeblingenV2.md @@ -0,0 +1,361 @@ +--- +title: FakeBoeblingenV2 +description: API reference for qiskit.providers.fake_provider.FakeBoeblingenV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBoeblingenV2 +--- + +# FakeBoeblingenV2 + + + +`qiskit.providers.fake_provider.FakeBoeblingenV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/boeblingen/fake_boeblingen.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Boeblingen V2 backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_boeblingen'` + + + +### conf\_filename + +`= 'conf_boeblingen.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_boeblingen.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/boeblingen'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBoeblingenV2.run "qiskit.providers.fake_provider.FakeBoeblingenV2.run") method. + + + +### props\_filename + +`= 'props_boeblingen.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogota.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogota.md new file mode 100644 index 00000000000..6ff305d3757 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogota.md @@ -0,0 +1,179 @@ +--- +title: FakeBogota +description: API reference for qiskit.providers.fake_provider.FakeBogota +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBogota +--- + +# FakeBogota + + + +`qiskit.providers.fake_provider.FakeBogota`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/bogota/fake_bogota.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_bogota'` + + + +### conf\_filename + +`= 'conf_bogota.json'` + + + +### defs\_filename + +`= 'defs_bogota.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/bogota'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBogota.run "qiskit.providers.fake_provider.FakeBogota.run") method. + + + +### props\_filename + +`= 'props_bogota.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogotaV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogotaV2.md new file mode 100644 index 00000000000..4eac6b1bd8a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBogotaV2.md @@ -0,0 +1,351 @@ +--- +title: FakeBogotaV2 +description: API reference for qiskit.providers.fake_provider.FakeBogotaV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBogotaV2 +--- + +# FakeBogotaV2 + + + +`qiskit.providers.fake_provider.FakeBogotaV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/bogota/fake_bogota.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_bogota'` + + + +### conf\_filename + +`= 'conf_bogota.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_bogota.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/bogota'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBogotaV2.run "qiskit.providers.fake_provider.FakeBogotaV2.run") method. + + + +### props\_filename + +`= 'props_bogota.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklyn.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklyn.md new file mode 100644 index 00000000000..2daad89ac54 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklyn.md @@ -0,0 +1,179 @@ +--- +title: FakeBrooklyn +description: API reference for qiskit.providers.fake_provider.FakeBrooklyn +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBrooklyn +--- + +# FakeBrooklyn + + + +`qiskit.providers.fake_provider.FakeBrooklyn`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/brooklyn/fake_brooklyn.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake Brooklyn backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_brooklyn'` + + + +### conf\_filename + +`= 'conf_brooklyn.json'` + + + +### defs\_filename + +`= 'defs_brooklyn.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/brooklyn'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBrooklyn.run "qiskit.providers.fake_provider.FakeBrooklyn.run") method. + + + +### props\_filename + +`= 'props_brooklyn.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklynV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklynV2.md new file mode 100644 index 00000000000..a1361bfdc70 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBrooklynV2.md @@ -0,0 +1,351 @@ +--- +title: FakeBrooklynV2 +description: API reference for qiskit.providers.fake_provider.FakeBrooklynV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBrooklynV2 +--- + +# FakeBrooklynV2 + + + +`qiskit.providers.fake_provider.FakeBrooklynV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/brooklyn/fake_brooklyn.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Brooklyn V2 backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_brooklyn'` + + + +### conf\_filename + +`= 'conf_brooklyn.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_brooklyn.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/brooklyn'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBrooklynV2.run "qiskit.providers.fake_provider.FakeBrooklynV2.run") method. + + + +### props\_filename + +`= 'props_brooklyn.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlington.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlington.md new file mode 100644 index 00000000000..c25f28d6cff --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlington.md @@ -0,0 +1,171 @@ +--- +title: FakeBurlington +description: API reference for qiskit.providers.fake_provider.FakeBurlington +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBurlington +--- + +# FakeBurlington + + + +`qiskit.providers.fake_provider.FakeBurlington`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/burlington/fake_burlington.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 3 ↔ 4 + ↕ + 2 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_burlington'` + + + +### conf\_filename + +`= 'conf_burlington.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/burlington'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBurlington.run "qiskit.providers.fake_provider.FakeBurlington.run") method. + + + +### props\_filename + +`= 'props_burlington.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlingtonV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlingtonV2.md new file mode 100644 index 00000000000..0430794cfdf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeBurlingtonV2.md @@ -0,0 +1,357 @@ +--- +title: FakeBurlingtonV2 +description: API reference for qiskit.providers.fake_provider.FakeBurlingtonV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeBurlingtonV2 +--- + +# FakeBurlingtonV2 + + + +`qiskit.providers.fake_provider.FakeBurlingtonV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/burlington/fake_burlington.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 3 ↔ 4 + ↕ + 2 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_burlington'` + + + +### conf\_filename + +`= 'conf_burlington.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/burlington'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeBurlingtonV2.run "qiskit.providers.fake_provider.FakeBurlingtonV2.run") method. + + + +### props\_filename + +`= 'props_burlington.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairo.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairo.md new file mode 100644 index 00000000000..bd142ad5068 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairo.md @@ -0,0 +1,179 @@ +--- +title: FakeCairo +description: API reference for qiskit.providers.fake_provider.FakeCairo +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeCairo +--- + +# FakeCairo + + + +`qiskit.providers.fake_provider.FakeCairo`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/cairo/fake_cairo.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_cairo'` + + + +### conf\_filename + +`= 'conf_cairo.json'` + + + +### defs\_filename + +`= 'defs_cairo.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/cairo'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeCairo.run "qiskit.providers.fake_provider.FakeCairo.run") method. + + + +### props\_filename + +`= 'props_cairo.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairoV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairoV2.md new file mode 100644 index 00000000000..36a4d8d5069 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCairoV2.md @@ -0,0 +1,351 @@ +--- +title: FakeCairoV2 +description: API reference for qiskit.providers.fake_provider.FakeCairoV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeCairoV2 +--- + +# FakeCairoV2 + + + +`qiskit.providers.fake_provider.FakeCairoV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/cairo/fake_cairo.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_cairo'` + + + +### conf\_filename + +`= 'conf_cairo.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_cairo.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/cairo'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeCairoV2.run "qiskit.providers.fake_provider.FakeCairoV2.run") method. + + + +### props\_filename + +`= 'props_cairo.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridge.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridge.md new file mode 100644 index 00000000000..5640ec9a5f9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridge.md @@ -0,0 +1,177 @@ +--- +title: FakeCambridge +description: API reference for qiskit.providers.fake_provider.FakeCambridge +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeCambridge +--- + +# FakeCambridge + + + +`qiskit.providers.fake_provider.FakeCambridge`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/cambridge/fake_cambridge.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake Cambridge backend. + +```python + 00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ + 05 06 + ↕ ↕ +07 ↔ 08 ↔ 09 ↔ 10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 ↔ 15 +↕ ↕ ↕ +16 17 18 +↕ ↕ ↕ +19 ↔ 20 ↔ 21 ↔ 22 ↔ 23 ↔ 24 ↔ 25 ↔ 26 ↔ 27 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_cambridge'` + + + +### conf\_filename + +`= 'conf_cambridge.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/cambridge'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeCambridge.run "qiskit.providers.fake_provider.FakeCambridge.run") method. + + + +### props\_filename + +`= 'props_cambridge.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridgeV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridgeV2.md new file mode 100644 index 00000000000..c0ab5a7d81b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCambridgeV2.md @@ -0,0 +1,363 @@ +--- +title: FakeCambridgeV2 +description: API reference for qiskit.providers.fake_provider.FakeCambridgeV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeCambridgeV2 +--- + +# FakeCambridgeV2 + + + +`qiskit.providers.fake_provider.FakeCambridgeV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/cambridge/fake_cambridge.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Cambridge backend. + +```python + 00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ + 05 06 + ↕ ↕ +07 ↔ 08 ↔ 09 ↔ 10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 ↔ 15 +↕ ↕ ↕ +16 17 18 +↕ ↕ ↕ +19 ↔ 20 ↔ 21 ↔ 22 ↔ 23 ↔ 24 ↔ 25 ↔ 26 ↔ 27 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_cambridge'` + + + +### conf\_filename + +`= 'conf_cambridge.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/cambridge'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeCambridgeV2.run "qiskit.providers.fake_provider.FakeCambridgeV2.run") method. + + + +### props\_filename + +`= 'props_cambridge.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablanca.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablanca.md new file mode 100644 index 00000000000..d80410150a7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablanca.md @@ -0,0 +1,179 @@ +--- +title: FakeCasablanca +description: API reference for qiskit.providers.fake_provider.FakeCasablanca +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeCasablanca +--- + +# FakeCasablanca + + + +`qiskit.providers.fake_provider.FakeCasablanca`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/casablanca/fake_casablanca.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 7 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_casablanca'` + + + +### conf\_filename + +`= 'conf_casablanca.json'` + + + +### defs\_filename + +`= 'defs_casablanca.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/casablanca'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeCasablanca.run "qiskit.providers.fake_provider.FakeCasablanca.run") method. + + + +### props\_filename + +`= 'props_casablanca.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablancaV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablancaV2.md new file mode 100644 index 00000000000..58025f7fd6e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeCasablancaV2.md @@ -0,0 +1,351 @@ +--- +title: FakeCasablancaV2 +description: API reference for qiskit.providers.fake_provider.FakeCasablancaV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeCasablancaV2 +--- + +# FakeCasablancaV2 + + + +`qiskit.providers.fake_provider.FakeCasablancaV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/casablanca/fake_casablanca.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 7 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_casablanca'` + + + +### conf\_filename + +`= 'conf_casablanca.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_casablanca.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/casablanca'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeCasablancaV2.run "qiskit.providers.fake_provider.FakeCasablancaV2.run") method. + + + +### props\_filename + +`= 'props_casablanca.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssex.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssex.md new file mode 100644 index 00000000000..21fa2f931f9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssex.md @@ -0,0 +1,173 @@ +--- +title: FakeEssex +description: API reference for qiskit.providers.fake_provider.FakeEssex +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeEssex +--- + +# FakeEssex + + + +`qiskit.providers.fake_provider.FakeEssex`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/essex/fake_essex.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 2 + ↕ + 3 + ↕ + 4 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_essex'` + + + +### conf\_filename + +`= 'conf_essex.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/essex'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeEssex.run "qiskit.providers.fake_provider.FakeEssex.run") method. + + + +### props\_filename + +`= 'props_essex.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssexV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssexV2.md new file mode 100644 index 00000000000..a9438bad9a8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeEssexV2.md @@ -0,0 +1,359 @@ +--- +title: FakeEssexV2 +description: API reference for qiskit.providers.fake_provider.FakeEssexV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeEssexV2 +--- + +# FakeEssexV2 + + + +`qiskit.providers.fake_provider.FakeEssexV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/essex/fake_essex.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 2 + ↕ + 3 + ↕ + 4 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_essex'` + + + +### conf\_filename + +`= 'conf_essex.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/essex'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeEssexV2.run "qiskit.providers.fake_provider.FakeEssexV2.run") method. + + + +### props\_filename + +`= 'props_essex.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGeneva.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGeneva.md new file mode 100644 index 00000000000..980ec95e6b4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGeneva.md @@ -0,0 +1,351 @@ +--- +title: FakeGeneva +description: API reference for qiskit.providers.fake_provider.FakeGeneva +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeGeneva +--- + +# FakeGeneva + + + +`qiskit.providers.fake_provider.FakeGeneva`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/geneva/fake_geneva.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_geneva'` + + + +### conf\_filename + +`= 'conf_geneva.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_geneva.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/geneva'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeGeneva.run "qiskit.providers.fake_provider.FakeGeneva.run") method. + + + +### props\_filename + +`= 'props_geneva.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupe.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupe.md new file mode 100644 index 00000000000..130768b8213 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupe.md @@ -0,0 +1,179 @@ +--- +title: FakeGuadalupe +description: API reference for qiskit.providers.fake_provider.FakeGuadalupe +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeGuadalupe +--- + +# FakeGuadalupe + + + +`qiskit.providers.fake_provider.FakeGuadalupe`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/guadalupe/fake_guadalupe.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 16 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_guadalupe'` + + + +### conf\_filename + +`= 'conf_guadalupe.json'` + + + +### defs\_filename + +`= 'defs_guadalupe.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/guadalupe'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeGuadalupe.run "qiskit.providers.fake_provider.FakeGuadalupe.run") method. + + + +### props\_filename + +`= 'props_guadalupe.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupeV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupeV2.md new file mode 100644 index 00000000000..33b4015eb5f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeGuadalupeV2.md @@ -0,0 +1,351 @@ +--- +title: FakeGuadalupeV2 +description: API reference for qiskit.providers.fake_provider.FakeGuadalupeV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeGuadalupeV2 +--- + +# FakeGuadalupeV2 + + + +`qiskit.providers.fake_provider.FakeGuadalupeV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/guadalupe/fake_guadalupe.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 16 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_guadalupe'` + + + +### conf\_filename + +`= 'conf_guadalupe.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_guadalupe.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/guadalupe'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeGuadalupeV2.run "qiskit.providers.fake_provider.FakeGuadalupeV2.run") method. + + + +### props\_filename + +`= 'props_guadalupe.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoi.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoi.md new file mode 100644 index 00000000000..9d90f359eb3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoi.md @@ -0,0 +1,179 @@ +--- +title: FakeHanoi +description: API reference for qiskit.providers.fake_provider.FakeHanoi +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeHanoi +--- + +# FakeHanoi + + + +`qiskit.providers.fake_provider.FakeHanoi`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/hanoi/fake_hanoi.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_hanoi'` + + + +### conf\_filename + +`= 'conf_hanoi.json'` + + + +### defs\_filename + +`= 'defs_hanoi.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/hanoi'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeHanoi.run "qiskit.providers.fake_provider.FakeHanoi.run") method. + + + +### props\_filename + +`= 'props_hanoi.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoiV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoiV2.md new file mode 100644 index 00000000000..539551b2173 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeHanoiV2.md @@ -0,0 +1,351 @@ +--- +title: FakeHanoiV2 +description: API reference for qiskit.providers.fake_provider.FakeHanoiV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeHanoiV2 +--- + +# FakeHanoiV2 + + + +`qiskit.providers.fake_provider.FakeHanoiV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/hanoi/fake_hanoi.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_hanoi'` + + + +### conf\_filename + +`= 'conf_hanoi.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_hanoi.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/hanoi'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeHanoiV2.run "qiskit.providers.fake_provider.FakeHanoiV2.run") method. + + + +### props\_filename + +`= 'props_hanoi.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakarta.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakarta.md new file mode 100644 index 00000000000..420185985bc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakarta.md @@ -0,0 +1,179 @@ +--- +title: FakeJakarta +description: API reference for qiskit.providers.fake_provider.FakeJakarta +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeJakarta +--- + +# FakeJakarta + + + +`qiskit.providers.fake_provider.FakeJakarta`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/jakarta/fake_jakarta.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 7 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_jakarta'` + + + +### conf\_filename + +`= 'conf_jakarta.json'` + + + +### defs\_filename + +`= 'defs_jakarta.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/jakarta'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeJakarta.run "qiskit.providers.fake_provider.FakeJakarta.run") method. + + + +### props\_filename + +`= 'props_jakarta.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakartaV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakartaV2.md new file mode 100644 index 00000000000..0729c1f5e2d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJakartaV2.md @@ -0,0 +1,351 @@ +--- +title: FakeJakartaV2 +description: API reference for qiskit.providers.fake_provider.FakeJakartaV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeJakartaV2 +--- + +# FakeJakartaV2 + + + +`qiskit.providers.fake_provider.FakeJakartaV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/jakarta/fake_jakarta.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 7 qubit V2 backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_jakarta'` + + + +### conf\_filename + +`= 'conf_jakarta.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_jakarta.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/jakarta'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeJakartaV2.run "qiskit.providers.fake_provider.FakeJakartaV2.run") method. + + + +### props\_filename + +`= 'props_jakarta.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburg.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburg.md new file mode 100644 index 00000000000..7fb9dc3027a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburg.md @@ -0,0 +1,175 @@ +--- +title: FakeJohannesburg +description: API reference for qiskit.providers.fake_provider.FakeJohannesburg +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeJohannesburg +--- + +# FakeJohannesburg + + + +`qiskit.providers.fake_provider.FakeJohannesburg`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/johannesburg/fake_johannesburg.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake Johannesburg backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_johannesburg'` + + + +### conf\_filename + +`= 'conf_johannesburg.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/johannesburg'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeJohannesburg.run "qiskit.providers.fake_provider.FakeJohannesburg.run") method. + + + +### props\_filename + +`= 'props_johannesburg.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburgV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburgV2.md new file mode 100644 index 00000000000..dc7d1d3b773 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeJohannesburgV2.md @@ -0,0 +1,361 @@ +--- +title: FakeJohannesburgV2 +description: API reference for qiskit.providers.fake_provider.FakeJohannesburgV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeJohannesburgV2 +--- + +# FakeJohannesburgV2 + + + +`qiskit.providers.fake_provider.FakeJohannesburgV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/johannesburg/fake_johannesburg.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Johannesburg V2 backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_johannesburg'` + + + +### conf\_filename + +`= 'conf_johannesburg.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/johannesburg'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeJohannesburgV2.run "qiskit.providers.fake_provider.FakeJohannesburgV2.run") method. + + + +### props\_filename + +`= 'props_johannesburg.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkata.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkata.md new file mode 100644 index 00000000000..f3e357bc796 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkata.md @@ -0,0 +1,179 @@ +--- +title: FakeKolkata +description: API reference for qiskit.providers.fake_provider.FakeKolkata +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeKolkata +--- + +# FakeKolkata + + + +`qiskit.providers.fake_provider.FakeKolkata`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/kolkata/fake_kolkata.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_kolkata'` + + + +### conf\_filename + +`= 'conf_kolkata.json'` + + + +### defs\_filename + +`= 'defs_kolkata.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/kolkata'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeKolkata.run "qiskit.providers.fake_provider.FakeKolkata.run") method. + + + +### props\_filename + +`= 'props_kolkata.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkataV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkataV2.md new file mode 100644 index 00000000000..42593e480b5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeKolkataV2.md @@ -0,0 +1,351 @@ +--- +title: FakeKolkataV2 +description: API reference for qiskit.providers.fake_provider.FakeKolkataV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeKolkataV2 +--- + +# FakeKolkataV2 + + + +`qiskit.providers.fake_provider.FakeKolkataV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/kolkata/fake_kolkata.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_kolkata'` + + + +### conf\_filename + +`= 'conf_kolkata.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_kolkata.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/kolkata'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeKolkataV2.run "qiskit.providers.fake_provider.FakeKolkataV2.run") method. + + + +### props\_filename + +`= 'props_kolkata.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagos.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagos.md new file mode 100644 index 00000000000..f729a96ed89 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagos.md @@ -0,0 +1,179 @@ +--- +title: FakeLagos +description: API reference for qiskit.providers.fake_provider.FakeLagos +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeLagos +--- + +# FakeLagos + + + +`qiskit.providers.fake_provider.FakeLagos`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/lagos/fake_lagos.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 7 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_lagos'` + + + +### conf\_filename + +`= 'conf_lagos.json'` + + + +### defs\_filename + +`= 'defs_lagos.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/lagos'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeLagos.run "qiskit.providers.fake_provider.FakeLagos.run") method. + + + +### props\_filename + +`= 'props_lagos.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagosV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagosV2.md new file mode 100644 index 00000000000..bdb89acb1be --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLagosV2.md @@ -0,0 +1,351 @@ +--- +title: FakeLagosV2 +description: API reference for qiskit.providers.fake_provider.FakeLagosV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeLagosV2 +--- + +# FakeLagosV2 + + + +`qiskit.providers.fake_provider.FakeLagosV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/lagos/fake_lagos.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 7 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_lagos'` + + + +### conf\_filename + +`= 'conf_lagos.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_lagos.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/lagos'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeLagosV2.run "qiskit.providers.fake_provider.FakeLagosV2.run") method. + + + +### props\_filename + +`= 'props_lagos.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLima.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLima.md new file mode 100644 index 00000000000..8aa123e9440 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLima.md @@ -0,0 +1,179 @@ +--- +title: FakeLima +description: API reference for qiskit.providers.fake_provider.FakeLima +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeLima +--- + +# FakeLima + + + +`qiskit.providers.fake_provider.FakeLima`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/lima/fake_lima.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_lima'` + + + +### conf\_filename + +`= 'conf_lima.json'` + + + +### defs\_filename + +`= 'defs_lima.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/lima'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeLima.run "qiskit.providers.fake_provider.FakeLima.run") method. + + + +### props\_filename + +`= 'props_lima.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLimaV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLimaV2.md new file mode 100644 index 00000000000..eea49f07e50 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLimaV2.md @@ -0,0 +1,351 @@ +--- +title: FakeLimaV2 +description: API reference for qiskit.providers.fake_provider.FakeLimaV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeLimaV2 +--- + +# FakeLimaV2 + + + +`qiskit.providers.fake_provider.FakeLimaV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/lima/fake_lima.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_lima'` + + + +### conf\_filename + +`= 'conf_lima.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_lima.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/lima'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeLimaV2.run "qiskit.providers.fake_provider.FakeLimaV2.run") method. + + + +### props\_filename + +`= 'props_lima.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondon.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondon.md new file mode 100644 index 00000000000..60a91aedcb2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondon.md @@ -0,0 +1,173 @@ +--- +title: FakeLondon +description: API reference for qiskit.providers.fake_provider.FakeLondon +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeLondon +--- + +# FakeLondon + + + +`qiskit.providers.fake_provider.FakeLondon`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/london/fake_london.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 2 + ↕ + 3 + ↕ + 4 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_london'` + + + +### conf\_filename + +`= 'conf_london.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/london'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeLondon.run "qiskit.providers.fake_provider.FakeLondon.run") method. + + + +### props\_filename + +`= 'props_london.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondonV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondonV2.md new file mode 100644 index 00000000000..fcfc6e7f841 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeLondonV2.md @@ -0,0 +1,359 @@ +--- +title: FakeLondonV2 +description: API reference for qiskit.providers.fake_provider.FakeLondonV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeLondonV2 +--- + +# FakeLondonV2 + + + +`qiskit.providers.fake_provider.FakeLondonV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/london/fake_london.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 2 + ↕ + 3 + ↕ + 4 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_london'` + + + +### conf\_filename + +`= 'conf_london.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/london'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeLondonV2.run "qiskit.providers.fake_provider.FakeLondonV2.run") method. + + + +### props\_filename + +`= 'props_london.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattan.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattan.md new file mode 100644 index 00000000000..9a32e0955b1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattan.md @@ -0,0 +1,179 @@ +--- +title: FakeManhattan +description: API reference for qiskit.providers.fake_provider.FakeManhattan +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeManhattan +--- + +# FakeManhattan + + + +`qiskit.providers.fake_provider.FakeManhattan`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/manhattan/fake_manhattan.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake Manhattan backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_manhattan'` + + + +### conf\_filename + +`= 'conf_manhattan.json'` + + + +### defs\_filename + +`= 'defs_manhattan.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/manhattan'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeManhattan.run "qiskit.providers.fake_provider.FakeManhattan.run") method. + + + +### props\_filename + +`= 'props_manhattan.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattanV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattanV2.md new file mode 100644 index 00000000000..134433b9922 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManhattanV2.md @@ -0,0 +1,351 @@ +--- +title: FakeManhattanV2 +description: API reference for qiskit.providers.fake_provider.FakeManhattanV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeManhattanV2 +--- + +# FakeManhattanV2 + + + +`qiskit.providers.fake_provider.FakeManhattanV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/manhattan/fake_manhattan.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Manhattan backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_manhattan'` + + + +### conf\_filename + +`= 'conf_manhattan.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_manhattan.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/manhattan'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeManhattanV2.run "qiskit.providers.fake_provider.FakeManhattanV2.run") method. + + + +### props\_filename + +`= 'props_manhattan.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManila.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManila.md new file mode 100644 index 00000000000..06cb7ea89e5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManila.md @@ -0,0 +1,179 @@ +--- +title: FakeManila +description: API reference for qiskit.providers.fake_provider.FakeManila +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeManila +--- + +# FakeManila + + + +`qiskit.providers.fake_provider.FakeManila`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/manila/fake_manila.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_manila'` + + + +### conf\_filename + +`= 'conf_manila.json'` + + + +### defs\_filename + +`= 'defs_manila.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/manila'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeManila.run "qiskit.providers.fake_provider.FakeManila.run") method. + + + +### props\_filename + +`= 'props_manila.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManilaV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManilaV2.md new file mode 100644 index 00000000000..9e044312a50 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeManilaV2.md @@ -0,0 +1,351 @@ +--- +title: FakeManilaV2 +description: API reference for qiskit.providers.fake_provider.FakeManilaV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeManilaV2 +--- + +# FakeManilaV2 + + + +`qiskit.providers.fake_provider.FakeManilaV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/manila/fake_manila.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_manila'` + + + +### conf\_filename + +`= 'conf_manila.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_manila.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/manila'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeManilaV2.run "qiskit.providers.fake_provider.FakeManilaV2.run") method. + + + +### props\_filename + +`= 'props_manila.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourne.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourne.md new file mode 100644 index 00000000000..b4d052ae9f9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourne.md @@ -0,0 +1,140 @@ +--- +title: FakeMelbourne +description: API reference for qiskit.providers.fake_provider.FakeMelbourne +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMelbourne +--- + +# FakeMelbourne + + + +`qiskit.providers.fake_provider.FakeMelbourne`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/melbourne/fake_melbourne.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake 14 qubit backend. + +```python +0 ← 1 → 2 → 3 ← 4 ← 5 → 6 + ↑ ↑ ↑ ↓ ↓ ↓ + 13 → 12 ← 11 → 10 ← 9 → 8 ← 7 +``` + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMelbourne.run "qiskit.providers.fake_provider.FakeMelbourne.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourneV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourneV2.md new file mode 100644 index 00000000000..11b800978cb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMelbourneV2.md @@ -0,0 +1,351 @@ +--- +title: FakeMelbourneV2 +description: API reference for qiskit.providers.fake_provider.FakeMelbourneV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMelbourneV2 +--- + +# FakeMelbourneV2 + + + +`qiskit.providers.fake_provider.FakeMelbourneV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/melbourne/fake_melbourne.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 14 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_melbourne'` + + + +### conf\_filename + +`= 'conf_melbourne.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/melbourne'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMelbourneV2.run "qiskit.providers.fake_provider.FakeMelbourneV2.run") method. + + + +### props\_filename + +`= 'props_melbourne.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontreal.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontreal.md new file mode 100644 index 00000000000..c9bdc9f6fea --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontreal.md @@ -0,0 +1,179 @@ +--- +title: FakeMontreal +description: API reference for qiskit.providers.fake_provider.FakeMontreal +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMontreal +--- + +# FakeMontreal + + + +`qiskit.providers.fake_provider.FakeMontreal`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/montreal/fake_montreal.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_montreal'` + + + +### conf\_filename + +`= 'conf_montreal.json'` + + + +### defs\_filename + +`= 'defs_montreal.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/montreal'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMontreal.run "qiskit.providers.fake_provider.FakeMontreal.run") method. + + + +### props\_filename + +`= 'props_montreal.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontrealV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontrealV2.md new file mode 100644 index 00000000000..bdcad22bb37 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMontrealV2.md @@ -0,0 +1,351 @@ +--- +title: FakeMontrealV2 +description: API reference for qiskit.providers.fake_provider.FakeMontrealV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMontrealV2 +--- + +# FakeMontrealV2 + + + +`qiskit.providers.fake_provider.FakeMontrealV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/montreal/fake_montreal.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_montreal'` + + + +### conf\_filename + +`= 'conf_montreal.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_montreal.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/montreal'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMontrealV2.run "qiskit.providers.fake_provider.FakeMontrealV2.run") method. + + + +### props\_filename + +`= 'props_montreal.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbai.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbai.md new file mode 100644 index 00000000000..81126024ae9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbai.md @@ -0,0 +1,179 @@ +--- +title: FakeMumbai +description: API reference for qiskit.providers.fake_provider.FakeMumbai +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMumbai +--- + +# FakeMumbai + + + +`qiskit.providers.fake_provider.FakeMumbai`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/mumbai/fake_mumbai.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_mumbai'` + + + +### conf\_filename + +`= 'conf_mumbai.json'` + + + +### defs\_filename + +`= 'defs_mumbai.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/mumbai'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMumbai.run "qiskit.providers.fake_provider.FakeMumbai.run") method. + + + +### props\_filename + +`= 'props_mumbai.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiFractionalCX.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiFractionalCX.md new file mode 100644 index 00000000000..cde6caefb53 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiFractionalCX.md @@ -0,0 +1,327 @@ +--- +title: FakeMumbaiFractionalCX +description: API reference for qiskit.providers.fake_provider.FakeMumbaiFractionalCX +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMumbaiFractionalCX +--- + +# FakeMumbaiFractionalCX + + + +`qiskit.providers.fake_provider.FakeMumbaiFractionalCX`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_mumbai_v2.py "view source code") + +Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") + +A fake mumbai backend. + + + The class `qiskit.providers.fake_provider.fake_mumbai_v2.FakeMumbaiFractionalCX` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. Use the qiskit.providers.basic\_provider.GenericBackendV2 class instead. + + +## Attributes + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the output signal timestep + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMumbaiFractionalCX.run "qiskit.providers.fake_provider.FakeMumbaiFractionalCX.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +### run + + + +`run(run_input, **options)` + +Run on the backend. + +This method returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiV2.md new file mode 100644 index 00000000000..ea0c4ac6fed --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeMumbaiV2.md @@ -0,0 +1,351 @@ +--- +title: FakeMumbaiV2 +description: API reference for qiskit.providers.fake_provider.FakeMumbaiV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeMumbaiV2 +--- + +# FakeMumbaiV2 + + + +`qiskit.providers.fake_provider.FakeMumbaiV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/mumbai/fake_mumbai.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_mumbai'` + + + +### conf\_filename + +`= 'conf_mumbai.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_mumbai.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/mumbai'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeMumbaiV2.run "qiskit.providers.fake_provider.FakeMumbaiV2.run") method. + + + +### props\_filename + +`= 'props_mumbai.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobi.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobi.md new file mode 100644 index 00000000000..86b26188dd9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobi.md @@ -0,0 +1,179 @@ +--- +title: FakeNairobi +description: API reference for qiskit.providers.fake_provider.FakeNairobi +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeNairobi +--- + +# FakeNairobi + + + +`qiskit.providers.fake_provider.FakeNairobi`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/nairobi/fake_nairobi.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 7 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_nairobi'` + + + +### conf\_filename + +`= 'conf_nairobi.json'` + + + +### defs\_filename + +`= 'defs_nairobi.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/nairobi'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeNairobi.run "qiskit.providers.fake_provider.FakeNairobi.run") method. + + + +### props\_filename + +`= 'props_nairobi.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobiV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobiV2.md new file mode 100644 index 00000000000..03ae5c94179 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeNairobiV2.md @@ -0,0 +1,351 @@ +--- +title: FakeNairobiV2 +description: API reference for qiskit.providers.fake_provider.FakeNairobiV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeNairobiV2 +--- + +# FakeNairobiV2 + + + +`qiskit.providers.fake_provider.FakeNairobiV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/nairobi/fake_nairobi.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 7 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_nairobi'` + + + +### conf\_filename + +`= 'conf_nairobi.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_nairobi.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/nairobi'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeNairobiV2.run "qiskit.providers.fake_provider.FakeNairobiV2.run") method. + + + +### props\_filename + +`= 'props_nairobi.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse2Q.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse2Q.md new file mode 100644 index 00000000000..6ab944e6a7d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse2Q.md @@ -0,0 +1,149 @@ +--- +title: FakeOpenPulse2Q +description: API reference for qiskit.providers.fake_provider.FakeOpenPulse2Q +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeOpenPulse2Q +--- + +# FakeOpenPulse2Q + + + +`qiskit.providers.fake_provider.FakeOpenPulse2Q`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_openpulse_2q.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake 2 qubit backend for pulse test. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeOpenPulse2Q.run "qiskit.providers.fake_provider.FakeOpenPulse2Q.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Return the default pulse-related settings provided by the backend (such as gate to Schedule mappings). + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return the measured characteristics of the backend. + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse3Q.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse3Q.md new file mode 100644 index 00000000000..bcc6a63fe3e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOpenPulse3Q.md @@ -0,0 +1,147 @@ +--- +title: FakeOpenPulse3Q +description: API reference for qiskit.providers.fake_provider.FakeOpenPulse3Q +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeOpenPulse3Q +--- + +# FakeOpenPulse3Q + + + +`qiskit.providers.fake_provider.FakeOpenPulse3Q`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_openpulse_3q.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +Trivial extension of the FakeOpenPulse2Q. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeOpenPulse3Q.run "qiskit.providers.fake_provider.FakeOpenPulse3Q.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return backend properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOslo.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOslo.md new file mode 100644 index 00000000000..df4b4cde628 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOslo.md @@ -0,0 +1,351 @@ +--- +title: FakeOslo +description: API reference for qiskit.providers.fake_provider.FakeOslo +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeOslo +--- + +# FakeOslo + + + +`qiskit.providers.fake_provider.FakeOslo`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/oslo/fake_oslo.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 7 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_oslo'` + + + +### conf\_filename + +`= 'conf_oslo.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_oslo.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/oslo'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeOslo.run "qiskit.providers.fake_provider.FakeOslo.run") method. + + + +### props\_filename + +`= 'props_oslo.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurense.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurense.md new file mode 100644 index 00000000000..f535ff5aeb3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurense.md @@ -0,0 +1,171 @@ +--- +title: FakeOurense +description: API reference for qiskit.providers.fake_provider.FakeOurense +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeOurense +--- + +# FakeOurense + + + +`qiskit.providers.fake_provider.FakeOurense`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/ourense/fake_ourense.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 3 ↔ 4 + ↕ + 2 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_ourense'` + + + +### conf\_filename + +`= 'conf_ourense.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/ourense'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeOurense.run "qiskit.providers.fake_provider.FakeOurense.run") method. + + + +### props\_filename + +`= 'props_ourense.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurenseV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurenseV2.md new file mode 100644 index 00000000000..6730e7e50e4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeOurenseV2.md @@ -0,0 +1,357 @@ +--- +title: FakeOurenseV2 +description: API reference for qiskit.providers.fake_provider.FakeOurenseV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeOurenseV2 +--- + +# FakeOurenseV2 + + + +`qiskit.providers.fake_provider.FakeOurenseV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/ourense/fake_ourense.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 3 ↔ 4 + ↕ + 2 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_ourense'` + + + +### conf\_filename + +`= 'conf_ourense.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/ourense'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeOurenseV2.run "qiskit.providers.fake_provider.FakeOurenseV2.run") method. + + + +### props\_filename + +`= 'props_ourense.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParis.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParis.md new file mode 100644 index 00000000000..20ccdcdc055 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParis.md @@ -0,0 +1,191 @@ +--- +title: FakeParis +description: API reference for qiskit.providers.fake_provider.FakeParis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeParis +--- + +# FakeParis + + + +`qiskit.providers.fake_provider.FakeParis`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/paris/fake_paris.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake Paris backend. + +```python + 06 17 + ↕ ↕ +00 ↔ 01 ↔ 04 ↔ 07 ↔ 10 ↔ 12 ↔ 15 ↔ 18 ↔ 20 ↔ 23 + ↕ ↕ ↕ + 02 13 24 + ↕ ↕ ↕ + 03 ↔ 05 ↔ 08 ↔ 11 ↔ 14 ↔ 16 ↔ 19 ↔ 22 ↔ 25 ↔ 26 + ↕ ↕ + 09 20 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_paris'` + + + +### conf\_filename + +`= 'conf_paris.json'` + + + +### defs\_filename + +`= 'defs_paris.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/paris'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeParis.run "qiskit.providers.fake_provider.FakeParis.run") method. + + + +### props\_filename + +`= 'props_paris.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParisV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParisV2.md new file mode 100644 index 00000000000..8b0eb62da97 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeParisV2.md @@ -0,0 +1,363 @@ +--- +title: FakeParisV2 +description: API reference for qiskit.providers.fake_provider.FakeParisV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeParisV2 +--- + +# FakeParisV2 + + + +`qiskit.providers.fake_provider.FakeParisV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/paris/fake_paris.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Paris backend. + +```python + 06 17 + ↕ ↕ +00 ↔ 01 ↔ 04 ↔ 07 ↔ 10 ↔ 12 ↔ 15 ↔ 18 ↔ 20 ↔ 23 + ↕ ↕ ↕ + 02 13 24 + ↕ ↕ ↕ + 03 ↔ 05 ↔ 08 ↔ 11 ↔ 14 ↔ 16 ↔ 19 ↔ 22 ↔ 25 ↔ 26 + ↕ ↕ + 09 20 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_paris'` + + + +### conf\_filename + +`= 'conf_paris.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_paris.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/paris'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeParisV2.run "qiskit.providers.fake_provider.FakeParisV2.run") method. + + + +### props\_filename + +`= 'props_paris.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePerth.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePerth.md new file mode 100644 index 00000000000..ca06118ac85 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePerth.md @@ -0,0 +1,351 @@ +--- +title: FakePerth +description: API reference for qiskit.providers.fake_provider.FakePerth +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakePerth +--- + +# FakePerth + + + +`qiskit.providers.fake_provider.FakePerth`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/perth/fake_perth.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 7 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_perth'` + + + +### conf\_filename + +`= 'conf_perth.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_perth.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/perth'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakePerth.run "qiskit.providers.fake_provider.FakePerth.run") method. + + + +### props\_filename + +`= 'props_perth.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsie.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsie.md new file mode 100644 index 00000000000..91befe7582d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsie.md @@ -0,0 +1,144 @@ +--- +title: FakePoughkeepsie +description: API reference for qiskit.providers.fake_provider.FakePoughkeepsie +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakePoughkeepsie +--- + +# FakePoughkeepsie + + + +`qiskit.providers.fake_provider.FakePoughkeepsie`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/poughkeepsie/fake_poughkeepsie.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake Poughkeepsie backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakePoughkeepsie.run "qiskit.providers.fake_provider.FakePoughkeepsie.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsieV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsieV2.md new file mode 100644 index 00000000000..779bf664d49 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePoughkeepsieV2.md @@ -0,0 +1,351 @@ +--- +title: FakePoughkeepsieV2 +description: API reference for qiskit.providers.fake_provider.FakePoughkeepsieV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakePoughkeepsieV2 +--- + +# FakePoughkeepsieV2 + + + +`qiskit.providers.fake_provider.FakePoughkeepsieV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/poughkeepsie/fake_poughkeepsie.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Poughkeepsie backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_poughkeepsie'` + + + +### conf\_filename + +`= 'conf_poughkeepsie.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_poughkeepsie.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/poughkeepsie'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakePoughkeepsieV2.run "qiskit.providers.fake_provider.FakePoughkeepsieV2.run") method. + + + +### props\_filename + +`= 'props_poughkeepsie.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePrague.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePrague.md new file mode 100644 index 00000000000..22450b68075 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakePrague.md @@ -0,0 +1,351 @@ +--- +title: FakePrague +description: API reference for qiskit.providers.fake_provider.FakePrague +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakePrague +--- + +# FakePrague + + + +`qiskit.providers.fake_provider.FakePrague`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/prague/fake_prague.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 33 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_prague'` + + + +### conf\_filename + +`= 'conf_prague.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/prague'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakePrague.run "qiskit.providers.fake_provider.FakePrague.run") method. + + + +### props\_filename + +`= 'props_prague.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProvider.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProvider.md new file mode 100644 index 00000000000..47b41df93e9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProvider.md @@ -0,0 +1,82 @@ +--- +title: FakeProvider +description: API reference for qiskit.providers.fake_provider.FakeProvider +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeProvider +--- + +# FakeProvider + + + +`qiskit.providers.fake_provider.FakeProvider`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_provider.py "view source code") + +Bases: [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.provider.ProviderV1") + +Fake provider containing fake V1 backends. + +Only filtering backends by name is implemented. This class contains all fake V1 backends available in the [`qiskit.providers.fake_provider`](providers_fake_provider#module-qiskit.providers.fake_provider "qiskit.providers.fake_provider"). + + + The class `qiskit.providers.fake_provider.fake_provider.FakeProvider` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. This class has been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeProviderExample instead of from qiskit.providers.fake\_provider import FakeProviderExample. + + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backends + + + +`backends(name=None, **kwargs)` + +Return a list of backends matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +**a list of Backends that match the filtering** + +criteria. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Backend](qiskit.providers.Backend "qiskit.providers.Backend")] + +### get\_backend + + + +`get_backend(name=None, **kwargs)` + +Return a single backend matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +a backend matching the filtering. + +**Return type** + +[Backend](qiskit.providers.Backend "qiskit.providers.Backend") + +**Raises** + +[**QiskitBackendNotFoundError**](providers#qiskit.providers.QiskitBackendNotFoundError "qiskit.providers.QiskitBackendNotFoundError") – if no backend could be found or more than one backend matches the filtering criteria. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProviderForBackendV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProviderForBackendV2.md new file mode 100644 index 00000000000..1bbe6ba104b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeProviderForBackendV2.md @@ -0,0 +1,82 @@ +--- +title: FakeProviderForBackendV2 +description: API reference for qiskit.providers.fake_provider.FakeProviderForBackendV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeProviderForBackendV2 +--- + +# FakeProviderForBackendV2 + + + +`qiskit.providers.fake_provider.FakeProviderForBackendV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_provider.py "view source code") + +Bases: [`ProviderV1`](qiskit.providers.ProviderV1 "qiskit.providers.provider.ProviderV1") + +Fake provider containing fake V2 backends. + +Only filtering backends by name is implemented. This class contains all fake V2 backends available in the [`qiskit.providers.fake_provider`](providers_fake_provider#module-qiskit.providers.fake_provider "qiskit.providers.fake_provider"). + + + The class `qiskit.providers.fake_provider.fake_provider.FakeProviderForBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. This class has been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeProviderExample instead of from qiskit.providers.fake\_provider import FakeProviderExample. + + +## Attributes + + + +### version + +`= 1` + +## Methods + +### backends + + + +`backends(name=None, **kwargs)` + +Return a list of backends matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +**a list of Backends that match the filtering** + +criteria. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[Backend](qiskit.providers.Backend "qiskit.providers.Backend")] + +### get\_backend + + + +`get_backend(name=None, **kwargs)` + +Return a single backend matching the specified filtering. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – name of the backend. +* **\*\*kwargs** – dict used for filtering. + +**Returns** + +a backend matching the filtering. + +**Return type** + +[Backend](qiskit.providers.Backend "qiskit.providers.Backend") + +**Raises** + +[**QiskitBackendNotFoundError**](providers#qiskit.providers.QiskitBackendNotFoundError "qiskit.providers.QiskitBackendNotFoundError") – if no backend could be found or more than one backend matches the filtering criteria. + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQasmSimulator.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQasmSimulator.md new file mode 100644 index 00000000000..511d6fe0daf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQasmSimulator.md @@ -0,0 +1,138 @@ +--- +title: FakeQasmSimulator +description: API reference for qiskit.providers.fake_provider.FakeQasmSimulator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeQasmSimulator +--- + +# FakeQasmSimulator + + + +`qiskit.providers.fake_provider.FakeQasmSimulator`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/fake_qasm_simulator.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake simulator backend. + + + The class `qiskit.providers.fake_provider.fake_qasm_simulator.FakeQasmSimulator` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. Use the qiskit.providers.basic\_provider.BasicSimulator class instead. + + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeQasmSimulator.run "qiskit.providers.fake_provider.FakeQasmSimulator.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return backend properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuito.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuito.md new file mode 100644 index 00000000000..e953171ce47 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuito.md @@ -0,0 +1,179 @@ +--- +title: FakeQuito +description: API reference for qiskit.providers.fake_provider.FakeQuito +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeQuito +--- + +# FakeQuito + + + +`qiskit.providers.fake_provider.FakeQuito`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/quito/fake_quito.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_quito'` + + + +### conf\_filename + +`= 'conf_quito.json'` + + + +### defs\_filename + +`= 'defs_quito.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/quito'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeQuito.run "qiskit.providers.fake_provider.FakeQuito.run") method. + + + +### props\_filename + +`= 'props_quito.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuitoV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuitoV2.md new file mode 100644 index 00000000000..85ec0362f1d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeQuitoV2.md @@ -0,0 +1,351 @@ +--- +title: FakeQuitoV2 +description: API reference for qiskit.providers.fake_provider.FakeQuitoV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeQuitoV2 +--- + +# FakeQuitoV2 + + + +`qiskit.providers.fake_provider.FakeQuitoV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/quito/fake_quito.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_quito'` + + + +### conf\_filename + +`= 'conf_quito.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_quito.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/quito'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeQuitoV2.run "qiskit.providers.fake_provider.FakeQuitoV2.run") method. + + + +### props\_filename + +`= 'props_quito.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochester.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochester.md new file mode 100644 index 00000000000..684a4621b06 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochester.md @@ -0,0 +1,165 @@ +--- +title: FakeRochester +description: API reference for qiskit.providers.fake_provider.FakeRochester +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeRochester +--- + +# FakeRochester + + + +`qiskit.providers.fake_provider.FakeRochester`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/rochester/fake_rochester.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake Rochester backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_rochester'` + + + +### conf\_filename + +`= 'conf_rochester.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/rochester'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeRochester.run "qiskit.providers.fake_provider.FakeRochester.run") method. + + + +### props\_filename + +`= 'props_rochester.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochesterV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochesterV2.md new file mode 100644 index 00000000000..99310cceab1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRochesterV2.md @@ -0,0 +1,351 @@ +--- +title: FakeRochesterV2 +description: API reference for qiskit.providers.fake_provider.FakeRochesterV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeRochesterV2 +--- + +# FakeRochesterV2 + + + +`qiskit.providers.fake_provider.FakeRochesterV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/rochester/fake_rochester.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Rochester backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_rochester'` + + + +### conf\_filename + +`= 'conf_rochester.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/rochester'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeRochesterV2.run "qiskit.providers.fake_provider.FakeRochesterV2.run") method. + + + +### props\_filename + +`= 'props_rochester.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRome.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRome.md new file mode 100644 index 00000000000..e5324286dc8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRome.md @@ -0,0 +1,179 @@ +--- +title: FakeRome +description: API reference for qiskit.providers.fake_provider.FakeRome +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeRome +--- + +# FakeRome + + + +`qiskit.providers.fake_provider.FakeRome`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/rome/fake_rome.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_rome'` + + + +### conf\_filename + +`= 'conf_rome.json'` + + + +### defs\_filename + +`= 'defs_rome.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/rome'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeRome.run "qiskit.providers.fake_provider.FakeRome.run") method. + + + +### props\_filename + +`= 'props_rome.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRomeV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRomeV2.md new file mode 100644 index 00000000000..62569343ac7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRomeV2.md @@ -0,0 +1,351 @@ +--- +title: FakeRomeV2 +description: API reference for qiskit.providers.fake_provider.FakeRomeV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeRomeV2 +--- + +# FakeRomeV2 + + + +`qiskit.providers.fake_provider.FakeRomeV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/rome/fake_rome.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_rome'` + + + +### conf\_filename + +`= 'conf_rome.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_rome.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/rome'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeRomeV2.run "qiskit.providers.fake_provider.FakeRomeV2.run") method. + + + +### props\_filename + +`= 'props_rome.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRueschlikon.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRueschlikon.md new file mode 100644 index 00000000000..28d30da9586 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeRueschlikon.md @@ -0,0 +1,140 @@ +--- +title: FakeRueschlikon +description: API reference for qiskit.providers.fake_provider.FakeRueschlikon +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeRueschlikon +--- + +# FakeRueschlikon + + + +`qiskit.providers.fake_provider.FakeRueschlikon`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/rueschlikon/fake_rueschlikon.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake 16 qubit backend. + +```python +1 → 2 → 3 → 4 ← 5 ← 6 → 7 ← 8 +↓ ↑ ↓ ↓ ↑ ↓ ↓ ↑ +0 ← 15 → 14 ← 13 ← 12 → 11 → 10 ← 9 +``` + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeRueschlikon.run "qiskit.providers.fake_provider.FakeRueschlikon.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Return backend properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiago.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiago.md new file mode 100644 index 00000000000..f373872433c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiago.md @@ -0,0 +1,179 @@ +--- +title: FakeSantiago +description: API reference for qiskit.providers.fake_provider.FakeSantiago +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSantiago +--- + +# FakeSantiago + + + +`qiskit.providers.fake_provider.FakeSantiago`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/santiago/fake_santiago.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake Santiago backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_santiago'` + + + +### conf\_filename + +`= 'conf_santiago.json'` + + + +### defs\_filename + +`= 'defs_santiago.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/santiago'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSantiago.run "qiskit.providers.fake_provider.FakeSantiago.run") method. + + + +### props\_filename + +`= 'props_santiago.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiagoV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiagoV2.md new file mode 100644 index 00000000000..c08f0dd9a2d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSantiagoV2.md @@ -0,0 +1,351 @@ +--- +title: FakeSantiagoV2 +description: API reference for qiskit.providers.fake_provider.FakeSantiagoV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSantiagoV2 +--- + +# FakeSantiagoV2 + + + +`qiskit.providers.fake_provider.FakeSantiagoV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/santiago/fake_santiago.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Santiago backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_santiago'` + + + +### conf\_filename + +`= 'conf_santiago.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_santiago.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/santiago'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSantiagoV2.run "qiskit.providers.fake_provider.FakeSantiagoV2.run") method. + + + +### props\_filename + +`= 'props_santiago.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSherbrooke.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSherbrooke.md new file mode 100644 index 00000000000..901be28c8fa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSherbrooke.md @@ -0,0 +1,351 @@ +--- +title: FakeSherbrooke +description: API reference for qiskit.providers.fake_provider.FakeSherbrooke +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSherbrooke +--- + +# FakeSherbrooke + + + +`qiskit.providers.fake_provider.FakeSherbrooke`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/sherbrooke/fake_sherbrooke.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 127 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_sherbrooke'` + + + +### conf\_filename + +`= 'conf_sherbrooke.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_sherbrooke.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/sherbrooke'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSherbrooke.run "qiskit.providers.fake_provider.FakeSherbrooke.run") method. + + + +### props\_filename + +`= 'props_sherbrooke.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingapore.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingapore.md new file mode 100644 index 00000000000..dfa5cd48049 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingapore.md @@ -0,0 +1,175 @@ +--- +title: FakeSingapore +description: API reference for qiskit.providers.fake_provider.FakeSingapore +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSingapore +--- + +# FakeSingapore + + + +`qiskit.providers.fake_provider.FakeSingapore`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/singapore/fake_singapore.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake Singapore backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_singapore'` + + + +### conf\_filename + +`= 'conf_singapore.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/singapore'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSingapore.run "qiskit.providers.fake_provider.FakeSingapore.run") method. + + + +### props\_filename + +`= 'props_singapore.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingaporeV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingaporeV2.md new file mode 100644 index 00000000000..4b4aad914fe --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSingaporeV2.md @@ -0,0 +1,361 @@ +--- +title: FakeSingaporeV2 +description: API reference for qiskit.providers.fake_provider.FakeSingaporeV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSingaporeV2 +--- + +# FakeSingaporeV2 + + + +`qiskit.providers.fake_provider.FakeSingaporeV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/singapore/fake_singapore.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake Singapore backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ↕ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ +15 ↔ 16 ↔ 17 ↔ 18 ↔ 19 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_singapore'` + + + +### conf\_filename + +`= 'conf_singapore.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/singapore'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSingaporeV2.run "qiskit.providers.fake_provider.FakeSingaporeV2.run") method. + + + +### props\_filename + +`= 'props_singapore.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydney.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydney.md new file mode 100644 index 00000000000..2532377b573 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydney.md @@ -0,0 +1,179 @@ +--- +title: FakeSydney +description: API reference for qiskit.providers.fake_provider.FakeSydney +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSydney +--- + +# FakeSydney + + + +`qiskit.providers.fake_provider.FakeSydney`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/sydney/fake_sydney.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_sydney'` + + + +### conf\_filename + +`= 'conf_sydney.json'` + + + +### defs\_filename + +`= 'defs_sydney.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/sydney'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSydney.run "qiskit.providers.fake_provider.FakeSydney.run") method. + + + +### props\_filename + +`= 'props_sydney.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydneyV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydneyV2.md new file mode 100644 index 00000000000..0c828f8a2d7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeSydneyV2.md @@ -0,0 +1,351 @@ +--- +title: FakeSydneyV2 +description: API reference for qiskit.providers.fake_provider.FakeSydneyV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeSydneyV2 +--- + +# FakeSydneyV2 + + + +`qiskit.providers.fake_provider.FakeSydneyV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/sydney/fake_sydney.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_sydney'` + + + +### conf\_filename + +`= 'conf_sydney.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_sydney.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/sydney'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeSydneyV2.run "qiskit.providers.fake_provider.FakeSydneyV2.run") method. + + + +### props\_filename + +`= 'props_sydney.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTenerife.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTenerife.md new file mode 100644 index 00000000000..e025630f306 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTenerife.md @@ -0,0 +1,142 @@ +--- +title: FakeTenerife +description: API reference for qiskit.providers.fake_provider.FakeTenerife +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeTenerife +--- + +# FakeTenerife + + + +`qiskit.providers.fake_provider.FakeTenerife`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/tenerife/fake_tenerife.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake 5 qubit backend. + +```python + 1 + ↙ ↑ +0 ← 2 ← 3 + ↑ ↙ + 4 +``` + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeTenerife.run "qiskit.providers.fake_provider.FakeTenerife.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties as recorded on 8/30/19. + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTokyo.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTokyo.md new file mode 100644 index 00000000000..ee77b3b6054 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTokyo.md @@ -0,0 +1,144 @@ +--- +title: FakeTokyo +description: API reference for qiskit.providers.fake_provider.FakeTokyo +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeTokyo +--- + +# FakeTokyo + + + +`qiskit.providers.fake_provider.FakeTokyo`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/tokyo/fake_tokyo.py "view source code") + +Bases: [`FakeBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeBackend "qiskit.providers.fake_provider.fake_backend.FakeBackend") + +A fake 20 qubit backend. + +```python +00 ↔ 01 ↔ 02 ↔ 03 ↔ 04 + ↕ ↕ ↕ ↕ ⤫ ↕ +05 ↔ 06 ↔ 07 ↔ 08 ↔ 09 + ↕ ⤫ ↕ ↕ ⤫ ↕ +10 ↔ 11 ↔ 12 ↔ 13 ↔ 14 + ↕ ↕ ⤫ ↕ ⤫ ↕ +15 ↔ 16 ↔ 17 18 19 +``` + +## Attributes + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeTokyo.run "qiskit.providers.fake_provider.FakeTokyo.run") method. + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties as recorded on 8/30/19. + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeToronto.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeToronto.md new file mode 100644 index 00000000000..ae7fdf5a175 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeToronto.md @@ -0,0 +1,179 @@ +--- +title: FakeToronto +description: API reference for qiskit.providers.fake_provider.FakeToronto +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeToronto +--- + +# FakeToronto + + + +`qiskit.providers.fake_provider.FakeToronto`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/toronto/fake_toronto.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 27 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_toronto'` + + + +### conf\_filename + +`= 'conf_toronto.json'` + + + +### defs\_filename + +`= 'defs_toronto.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/toronto'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeToronto.run "qiskit.providers.fake_provider.FakeToronto.run") method. + + + +### props\_filename + +`= 'props_toronto.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTorontoV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTorontoV2.md new file mode 100644 index 00000000000..67871fc518c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeTorontoV2.md @@ -0,0 +1,351 @@ +--- +title: FakeTorontoV2 +description: API reference for qiskit.providers.fake_provider.FakeTorontoV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeTorontoV2 +--- + +# FakeTorontoV2 + + + +`qiskit.providers.fake_provider.FakeTorontoV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/toronto/fake_toronto.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 27 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_toronto'` + + + +### conf\_filename + +`= 'conf_toronto.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_toronto.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/toronto'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeTorontoV2.run "qiskit.providers.fake_provider.FakeTorontoV2.run") method. + + + +### props\_filename + +`= 'props_toronto.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValencia.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValencia.md new file mode 100644 index 00000000000..9bf65823108 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValencia.md @@ -0,0 +1,179 @@ +--- +title: FakeValencia +description: API reference for qiskit.providers.fake_provider.FakeValencia +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeValencia +--- + +# FakeValencia + + + +`qiskit.providers.fake_provider.FakeValencia`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/valencia/fake_valencia.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 5 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_valencia'` + + + +### conf\_filename + +`= 'conf_valencia.json'` + + + +### defs\_filename + +`= 'defs_valencia.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/valencia'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeValencia.run "qiskit.providers.fake_provider.FakeValencia.run") method. + + + +### props\_filename + +`= 'props_valencia.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValenciaV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValenciaV2.md new file mode 100644 index 00000000000..571138ae955 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeValenciaV2.md @@ -0,0 +1,351 @@ +--- +title: FakeValenciaV2 +description: API reference for qiskit.providers.fake_provider.FakeValenciaV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeValenciaV2 +--- + +# FakeValenciaV2 + + + +`qiskit.providers.fake_provider.FakeValenciaV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/valencia/fake_valencia.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_valencia'` + + + +### conf\_filename + +`= 'conf_valencia.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_valencia.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/valencia'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeValenciaV2.run "qiskit.providers.fake_provider.FakeValenciaV2.run") method. + + + +### props\_filename + +`= 'props_valencia.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigo.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigo.md new file mode 100644 index 00000000000..08f64890972 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigo.md @@ -0,0 +1,171 @@ +--- +title: FakeVigo +description: API reference for qiskit.providers.fake_provider.FakeVigo +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeVigo +--- + +# FakeVigo + + + +`qiskit.providers.fake_provider.FakeVigo`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/vigo/fake_vigo.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 3 ↔ 4 + ↕ + 2 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_vigo'` + + + +### conf\_filename + +`= 'conf_vigo.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/vigo'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeVigo.run "qiskit.providers.fake_provider.FakeVigo.run") method. + + + +### props\_filename + +`= 'props_vigo.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigoV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigoV2.md new file mode 100644 index 00000000000..e19d42947ad --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeVigoV2.md @@ -0,0 +1,357 @@ +--- +title: FakeVigoV2 +description: API reference for qiskit.providers.fake_provider.FakeVigoV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeVigoV2 +--- + +# FakeVigoV2 + + + +`qiskit.providers.fake_provider.FakeVigoV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/vigo/fake_vigo.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +```python +0 ↔ 1 ↔ 3 ↔ 4 + ↕ + 2 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_vigo'` + + + +### conf\_filename + +`= 'conf_vigo.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/vigo'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeVigoV2.run "qiskit.providers.fake_provider.FakeVigoV2.run") method. + + + +### props\_filename + +`= 'props_vigo.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashington.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashington.md new file mode 100644 index 00000000000..692a131d72b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashington.md @@ -0,0 +1,179 @@ +--- +title: FakeWashington +description: API reference for qiskit.providers.fake_provider.FakeWashington +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeWashington +--- + +# FakeWashington + + + +`qiskit.providers.fake_provider.FakeWashington`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/washington/fake_washington.py "view source code") + +Bases: [`FakePulseBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakePulseBackend "qiskit.providers.fake_provider.fake_pulse_backend.FakePulseBackend") + +A fake 127 qubit backend. + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_washington'` + + + +### conf\_filename + +`= 'conf_washington.json'` + + + +### defs\_filename + +`= 'defs_washington.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/washington'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeWashington.run "qiskit.providers.fake_provider.FakeWashington.run") method. + + + +### props\_filename + +`= 'props_washington.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### defaults + + + +`defaults()` + +Returns a snapshot of device defaults + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashingtonV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashingtonV2.md new file mode 100644 index 00000000000..bb1b48fc453 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeWashingtonV2.md @@ -0,0 +1,351 @@ +--- +title: FakeWashingtonV2 +description: API reference for qiskit.providers.fake_provider.FakeWashingtonV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeWashingtonV2 +--- + +# FakeWashingtonV2 + + + +`qiskit.providers.fake_provider.FakeWashingtonV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/washington/fake_washington.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 127 qubit backend. + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_washington'` + + + +### conf\_filename + +`= 'conf_washington.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= 'defs_washington.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/washington'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeWashingtonV2.run "qiskit.providers.fake_provider.FakeWashingtonV2.run") method. + + + +### props\_filename + +`= 'props_washington.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktown.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktown.md new file mode 100644 index 00000000000..3806c7e9427 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktown.md @@ -0,0 +1,173 @@ +--- +title: FakeYorktown +description: API reference for qiskit.providers.fake_provider.FakeYorktown +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeYorktown +--- + +# FakeYorktown + + + +`qiskit.providers.fake_provider.FakeYorktown`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/yorktown/fake_yorktown.py "view source code") + +Bases: [`FakeQasmBackend`](providers_fake_provider#qiskit.providers.fake_provider.FakeQasmBackend "qiskit.providers.fake_provider.fake_qasm_backend.FakeQasmBackend") + +A fake 5 qubit backend. + +```python + 1 + / | +0 - 2 - 3 + | / + 4 +``` + +FakeBackend initializer. + +**Parameters** + +* **configuration** ([*BackendConfiguration*](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration")) – backend configuration +* **time\_alive** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – time to wait before returning result + +## Attributes + + + +### backend\_name + +`= 'fake_yorktown'` + + + +### conf\_filename + +`= 'conf_yorktown.json'` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/yorktown'` + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeYorktown.run "qiskit.providers.fake_provider.FakeYorktown.run") method. + + + +### props\_filename + +`= 'props_yorktown.json'` + + + +### version + +`= 1` + +## Methods + +### configuration + + + +`configuration()` + +Return the backend configuration. + +**Returns** + +the configuration for the backend. + +**Return type** + +[BackendConfiguration](qiskit.providers.models.BackendConfiguration "qiskit.providers.models.BackendConfiguration") + +### name + + + +`name()` + +Return the backend name. + +**Returns** + +the name of the backend. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### properties + + + +`properties()` + +Returns a snapshot of device properties + +### provider + + + +`provider()` + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + +### run + + + +`run(run_input, **kwargs)` + +Main job in simulator + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + +### status + + + +`status()` + +Return the backend status. + +**Returns** + +the status of the backend. + +**Return type** + +[BackendStatus](qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktownV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktownV2.md new file mode 100644 index 00000000000..631b917e9df --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.FakeYorktownV2.md @@ -0,0 +1,359 @@ +--- +title: FakeYorktownV2 +description: API reference for qiskit.providers.fake_provider.FakeYorktownV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.FakeYorktownV2 +--- + +# FakeYorktownV2 + + + +`qiskit.providers.fake_provider.FakeYorktownV2`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/backends/yorktown/fake_yorktown.py "view source code") + +Bases: [`FakeBackendV2`](providers_fake_provider#qiskit.providers.fake_provider.fake_backend.FakeBackendV2 "qiskit.providers.fake_provider.fake_backend.FakeBackendV2") + +A fake 5 qubit backend. + +```python + 1 + / | +0 - 2 - 3 + | / + 4 +``` + +FakeBackendV2 initializer. + + + The class `qiskit.providers.fake_provider.fake_backend.FakeBackendV2` is deprecated as of qiskit 0.46.0. It will be removed in qiskit 1.0. All fake backend instances based on real device snapshots (FakeVigo,\`FakeSherbrooke\`,…) have been migrated to the qiskit\_ibm\_runtime package. To migrate your code, run pip install qiskit-ibm-runtime and use from qiskit\_ibm\_runtime.fake\_provider import FakeExample instead of from qiskit.providers.fake\_provider import FakeExample. + + +## Attributes + + + +### backend\_name + +`= 'fake_yorktown'` + + + +### conf\_filename + +`= 'conf_yorktown.json'` + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### defs\_filename + +`= None` + + + +### dirname + +`= '/home/runner/work/qiskit/qiskit/qiskit/providers/fake_provider/backends/yorktown'` + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + +**Returns** + +The output signal timestep in seconds. + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + +Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The grouping of measurements which are multiplexed + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.FakeYorktownV2.run "qiskit.providers.fake_provider.FakeYorktownV2.run") method. + + + +### props\_filename + +`= 'props_yorktown.json'` + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + +A [`qiskit.transpiler.Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object for the backend. + +**Return type** + +[Target](qiskit.transpiler.Target "qiskit.transpiler.Target") + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the fake backend using a simulator. + +This method runs circuit jobs (an individual or a list of QuantumCircuit ) and pulse jobs (an individual or a list of Schedule or ScheduleBlock) using a [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using AerSimulator with noise model of the fake backend. Otherwise, jobs will be run using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") without noise. + +Currently noisy simulation of a pulse job is not supported yet in FakeBackendV2. + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit-aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.fake_provider.GenericBackendV2.md b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.GenericBackendV2.md new file mode 100644 index 00000000000..afa45f5f975 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.fake_provider.GenericBackendV2.md @@ -0,0 +1,354 @@ +--- +title: GenericBackendV2 +description: API reference for qiskit.providers.fake_provider.GenericBackendV2 +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.fake_provider.GenericBackendV2 +--- + +# GenericBackendV2 + + + +`qiskit.providers.fake_provider.GenericBackendV2(num_qubits, basis_gates=None, *, coupling_map=None, control_flow=False, calibrate_instructions=None, dtm=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/fake_provider/generic_backend_v2.py "view source code") + +Bases: [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") + +Generic [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") implementation with a configurable constructor. This class will return a [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") instance that runs on a local simulator (in the spirit of fake backends) and contains all the necessary information to test backend-interfacing components, such as the transpiler. A [`GenericBackendV2`](#qiskit.providers.fake_provider.GenericBackendV2 "qiskit.providers.fake_provider.GenericBackendV2") instance can be constructed from as little as a specified `num_qubits`, but users can additionally configure the basis gates, coupling map, ability to run dynamic circuits (control flow instructions), instruction calibrations and dtm. The remainder of the backend properties are generated by randomly sampling from default ranges extracted from historical IBM backend data. The seed for this random generation can be fixed to ensure the reproducibility of the backend output. This backend only supports gates in the standard library, if you need a more flexible backend, there is always the option to directly instantiate a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object to use for transpilation. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of qubits that will be used to construct the backend’s target. Note that, while there is no limit in the size of the target that can be constructed, this backend runs on local noisy simulators, and these might present limitations in the number of qubits that can be simulated. + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – List of basis gate names to be supported by the target. These must be part of the standard qiskit circuit library. The default set of basis gates is `["id", "rz", "sx", "x", "cx"]` The `"reset"`, `"delay"`, and `"measure"` instructions are always supported by default, even if not specified via `basis_gates`. + +* **coupling\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] |* [*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") *| None*) – + + Optional coupling map for the backend. Multiple formats are supported: + + 1. [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") instance + 2. List, must be given as an edge list representing the two qubit interactions supported by the backend, for example: `[[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]` + + If `coupling_map` is specified, it must match the number of qubits specified in `num_qubits`. If `coupling_map` is not specified, a fully connected coupling map will be generated with `num_qubits` qubits. + +* **control\_flow** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Flag to enable control flow directives on the target (defaults to False). + +* **calibrate\_instructions** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *|*[*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") *| None*) – + + Instruction calibration settings, this argument supports both boolean and [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") as input types, and is `None` by default: + + 1. If `calibrate_instructions==None`, no calibrations will be added to the target. + + 2. **If `calibrate_instructions==True`, all gates will be calibrated for all** + + qubits using the default pulse schedules generated internally. + + 3. **If `calibrate_instructions==False`, all gates will be “calibrated” for** + + all qubits with an empty pulse schedule. + + 4. **If an [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") instance is given, the calibrations** + + in this instruction schedule map will be appended to the target instead of the default pulse schedules (this allows for custom calibrations). + +* **dtm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – System time resolution of output signals in nanoseconds. None by default. + +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional seed for generation of default values. + +## Attributes + + + +### coupling\_map + +Return the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object + + + +### dt + +Return the system time resolution of input signals + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + + + +### dtm + +Return the system time resolution of output signals + + + +### instruction\_durations + +Return the [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object. + + + +### instruction\_schedule\_map + +Return the [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions defined in this backend’s target. + + + +### instructions + +A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + + + +### max\_circuits + + + +### meas\_map + + + +### num\_qubits + +Return the number of qubits the backend has. + + + +### operation\_names + +A list of instruction names that the backend supports. + + + +### operations + +A list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that the backend supports. + + + +### options + +Return the options for the backend + +The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit.providers.fake_provider.GenericBackendV2.run "qiskit.providers.fake_provider.GenericBackendV2.run") method. + + + +### provider + +Return the backend Provider. + +**Returns** + +the Provider responsible for the backend. + +**Return type** + +[Provider](qiskit.providers.Provider "qiskit.providers.Provider") + + + +### target + + + +### version + +`= 2` + + + +### name + +Name of the backend. + + + +### description + +Optional human-readable description. + + + +### online\_date + +Date that the backend came online. + + + +### backend\_version + +Version of the backend being provided. This is not the same as [`BackendV2.version`](qiskit.providers.BackendV2#version "qiskit.providers.BackendV2.version"), which is the version of the [`Backend`](qiskit.providers.Backend "qiskit.providers.Backend") abstract interface. + +## Methods + +### acquire\_channel + + + +`acquire_channel(qubit)` + +Return the acquisition channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement acquisition line. + +**Return type** + +[AcquireChannel](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### control\_channel + + + +`control_channel(qubits)` + +Return the secondary drive channel for the given qubit + +This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + +**Returns** + +The multi qubit control line. + +**Return type** + +List\[[ControlChannel](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### drive\_channel + + + +`drive_channel(qubit)` + +Return the drive channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit drive channel + +**Return type** + +[DriveChannel](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### measure\_channel + + + +`measure_channel(qubit)` + +Return the measure stimulus channel for the given qubit. + +This is required to be implemented if the backend supports Pulse scheduling. + +**Returns** + +The Qubit measurement stimulus line + +**Return type** + +[MeasureChannel](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the measurement mapping + +### qubit\_properties + + + +`qubit_properties(qubit)` + +Return QubitProperties for a given qubit. + +If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubit to get the [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for. This can be a single integer for 1 qubit or a list of qubits and a list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects will be returned in the same order + +**Returns** + +The [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – if the backend doesn’t support querying the qubit properties + +**Return type** + +[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties") | [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QubitProperties*](qiskit.providers.QubitProperties "qiskit.providers.backend.QubitProperties")] + +### run + + + +`run(run_input, **options)` + +Run on the backend using a simulator. + +This method runs circuit jobs (an individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") ) and pulse jobs (an individual or a list of [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")) using [`BasicSimulator`](qiskit.providers.basic_provider.BasicSimulator "qiskit.providers.basic_provider.BasicSimulator") or Aer simulator and returns a [`Job`](qiskit.providers.Job "qiskit.providers.Job") object. + +If qiskit-aer is installed, jobs will be run using the `AerSimulator` with noise model of the backend. Otherwise, jobs will be run using the `BasicSimulator` simulator without noise. + +Noisy simulations of pulse jobs are not yet supported in [`GenericBackendV2`](#qiskit.providers.fake_provider.GenericBackendV2 "qiskit.providers.fake_provider.GenericBackendV2"). + +**Parameters** + +* **run\_input** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An individual or a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"), or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") objects to run on the backend. +* **options** – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object, then the expectation is that the value specified will be used instead of what’s set in the options object. + +**Returns** + +The job object for the run + +**Return type** + +[Job](qiskit.providers.Job "qiskit.providers.Job") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a pulse job is supplied and qiskit\_aer is not installed. + +### set\_options + + + +`set_options(**fields)` + +Set the options fields for the backend + +This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. + +**Parameters** + +**fields** – The fields to update the options + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the field passed in is not part of the options + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.BackendConfiguration.md b/docs/api/qiskit/0.46/qiskit.providers.models.BackendConfiguration.md new file mode 100644 index 00000000000..b63ab408201 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.BackendConfiguration.md @@ -0,0 +1,138 @@ +--- +title: BackendConfiguration +description: API reference for qiskit.providers.models.BackendConfiguration +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.BackendConfiguration +--- + +# BackendConfiguration + + + +`qiskit.providers.models.BackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, supported_instructions=None, dynamic_reprate_enabled=False, rep_delay_range=None, default_rep_delay=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, dt=None, dtm=None, processor_type=None, parametric_pulses=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendconfiguration.py "view source code") + +Bases: [`QasmBackendConfiguration`](qiskit.providers.models.QasmBackendConfiguration "qiskit.providers.models.backendconfiguration.QasmBackendConfiguration") + +Backwards compat shim representing an abstract backend configuration. + +Initialize a QasmBackendConfiguration Object + +**Parameters** + +* **backend\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The backend name + +* **backend\_version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The backend version in the form X.Y.Z + +* **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits for the backend + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The list of strings for the basis gates of the backends + +* **gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The list of GateConfig objects for the basis gates of the backend + +* **local** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is local or False if remote + +* **simulator** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is a simulator + +* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend supports conditional operations + +* **open\_pulse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend supports OpenPulse + +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend supports memory + +* **max\_shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of shots allowed on the backend + +* **coupling\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The coupling map for the device + +* **supported\_instructions** (*List\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Instructions supported by the backend. + +* **dynamic\_reprate\_enabled** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. + +* **rep\_delay\_range** (*List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. + +* **default\_rep\_delay** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. + +* **max\_experiments** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of experiments per job + +* **sample\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Sample name for the backend + +* **n\_registers** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of register slots available for feedback (if conditional is True) + +* **register\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. + +* **configurable** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is configurable, if the backend is a simulator + +* **credits\_required** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if backend requires credits to run a job. + +* **online\_date** ([*datetime.datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")) – The date that the device went online + +* **display\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Alternate name field for the backend + +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A description for the backend + +* **tags** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of string tags to describe the backend + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Qubit drive channel timestep in nanoseconds. + +* **dtm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Measurement drive channel timestep in nanoseconds. + +* **processor\_type** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. + + * family: Processor family of this backend. + * revision: Revision version of this processor. + * segment: Segment this processor belongs to within a larger chip. + +* **parametric\_pulses** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` + +* **\*\*kwargs** – optional fields + +## Attributes + + + +### num\_qubits + +Returns the number of qubits. + +In future, n\_qubits should be replaced in favor of num\_qubits for consistent use throughout Qiskit. Until this is properly refactored, this property serves as intermediate solution. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new GateConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the GateConfig to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.BackendConfiguration.to_dict "qiskit.providers.models.BackendConfiguration.to_dict"). + +**Returns** + +The GateConfig from the input dictionary. + +**Return type** + +[GateConfig](qiskit.providers.models.GateConfig "qiskit.providers.models.GateConfig") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the GateConfig. + +**Returns** + +The dictionary form of the GateConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.BackendProperties.md b/docs/api/qiskit/0.46/qiskit.providers.models.BackendProperties.md new file mode 100644 index 00000000000..b29342ef9bd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.BackendProperties.md @@ -0,0 +1,320 @@ +--- +title: BackendProperties +description: API reference for qiskit.providers.models.BackendProperties +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.BackendProperties +--- + +# BackendProperties + + + +`qiskit.providers.models.BackendProperties(backend_name, backend_version, last_update_date, qubits, gates, general, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendproperties.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing backend properties + +This holds backend properties measured by the provider. All properties which are provided optionally. These properties may describe qubits, gates, or other general properties of the backend. + +Initialize a BackendProperties instance. + +**Parameters** + +* **backend\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Backend name. +* **backend\_version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Backend version in the form X.Y.Z. +* **last\_update\_date** ([*datetime.datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Last date/time that a property was updated. If specified as a `str`, it must be in ISO format. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – System qubit parameters as a list of lists of [`Nduv`](qiskit.providers.models.Nduv "qiskit.providers.models.Nduv") objects +* **gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – System gate parameters as a list of [`GateProperties`](qiskit.providers.models.GateProperties "qiskit.providers.models.GateProperties") objects +* **general** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – General parameters as a list of [`Nduv`](qiskit.providers.models.Nduv "qiskit.providers.models.Nduv") objects +* **kwargs** – optional additional fields + +## Methods + +### faulty\_gates + + + +`faulty_gates()` + +Return a list of faulty gates. + +### faulty\_qubits + + + +`faulty_qubits()` + +Return a list of faulty qubits. + +### frequency + + + +`frequency(qubit)` + +Return the frequency of the given qubit. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit for which to return frequency of. + +**Returns** + +Frequency of the given qubit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new BackendProperties object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the BackendProperties to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.BackendProperties.to_dict "qiskit.providers.models.BackendProperties.to_dict"). + +**Returns** + +The BackendProperties from the input dictionary. + +**Return type** + +[BackendProperties](#qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") + +### gate\_error + + + +`gate_error(gate, qubits)` + +Return gate error estimates from backend properties. + +**Parameters** + +* **gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The gate for which to get the error. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The specific qubits for the gate. + +**Returns** + +Gate error of the given gate and qubit(s). + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### gate\_length + + + +`gate_length(gate, qubits)` + +Return the duration of the gate in units of seconds. + +**Parameters** + +* **gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The gate for which to get the duration. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The specific qubits for the gate. + +**Returns** + +Gate length of the given gate and qubit(s). + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### gate\_property + + + +`gate_property(gate, qubits=None, name=None)` + +Return the property of the given gate. + +**Parameters** + +* **gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of the gate. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – The qubit to find the property for. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Optionally used to specify which gate property to return. + +**Returns** + +Gate property as a tuple of the value and the time it was measured. + +**Raises** + +[**BackendPropertyError**](providers#qiskit.providers.BackendPropertyError "qiskit.providers.BackendPropertyError") – If the property is not found or name is specified but qubit is not. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")] + +### is\_gate\_operational + + + +`is_gate_operational(gate, qubits=None)` + +Return the operational status of the given gate. + +**Parameters** + +* **gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of the gate. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – The qubit to find the operational status for. + +**Returns** + +Operational status of the given gate. True if the gate is operational, False otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_qubit\_operational + + + +`is_qubit_operational(qubit)` + +Return the operational status of the given qubit. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit for which to return operational status of. + +**Returns** + +Operational status of the given qubit. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### qubit\_property + + + +`qubit_property(qubit, name=None)` + +Return the property of the given qubit. + +**Parameters** + +* **qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The property to look for. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Optionally used to specify within the hierarchy which property to return. + +**Returns** + +Qubit property as a tuple of the value and the time it was measured. + +**Raises** + +[**BackendPropertyError**](providers#qiskit.providers.BackendPropertyError "qiskit.providers.BackendPropertyError") – If the property is not found. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")] + +### readout\_error + + + +`readout_error(qubit)` + +Return the readout error of the given qubit. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit for which to return the readout error of. + +**Returns** + +Readout error of the given qubit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### readout\_length + + + +`readout_length(qubit)` + +Return the readout length \[sec] of the given qubit. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit for which to return the readout length of. + +**Returns** + +Readout length of the given qubit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### t1 + + + +`t1(qubit)` + +Return the T1 time of the given qubit. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit for which to return the T1 time of. + +**Returns** + +T1 time of the given qubit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### t2 + + + +`t2(qubit)` + +Return the T2 time of the given qubit. + +**Parameters** + +**qubit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit for which to return the T2 time of. + +**Returns** + +T2 time of the given qubit. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the BackendProperties. + +**Returns** + +The dictionary form of the BackendProperties. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.BackendStatus.md b/docs/api/qiskit/0.46/qiskit.providers.models.BackendStatus.md new file mode 100644 index 00000000000..7cbf0fa6907 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.BackendStatus.md @@ -0,0 +1,70 @@ +--- +title: BackendStatus +description: API reference for qiskit.providers.models.BackendStatus +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.BackendStatus +--- + +# BackendStatus + + + +`qiskit.providers.models.BackendStatus(backend_name, backend_version, operational, pending_jobs, status_msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendstatus.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing Backend Status. + +Initialize a BackendStatus object + +**Parameters** + +* **backend\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The backend’s name +* **backend\_version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The backend’s version of the form X.Y.Z +* **operational** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is operational +* **pending\_jobs** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of pending jobs on the backend +* **status\_msg** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The status msg for the backend + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the backend version is in an invalid format + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new BackendStatus object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the BaseBakend to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.BackendStatus.to_dict "qiskit.providers.models.BackendStatus.to_dict"). + +**Returns** + +The BackendStatus from the input dictionary. + +**Return type** + +[BackendStatus](#qiskit.providers.models.BackendStatus "qiskit.providers.models.BackendStatus") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the BackendStatus. + +**Returns** + +The dictionary form of the QobjHeader. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.Command.md b/docs/api/qiskit/0.46/qiskit.providers.models.Command.md new file mode 100644 index 00000000000..50a6ba8a580 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.Command.md @@ -0,0 +1,71 @@ +--- +title: Command +description: API reference for qiskit.providers.models.Command +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.Command +--- + +# Command + + + +`qiskit.providers.models.Command(name, qubits=None, sequence=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/pulsedefaults.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing a Command. + + + +### name + +Pulse command name. + +Initialize a Command object + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the command +* **qubits** – The qubits for the command +* **sequence** ([*PulseQobjInstruction*](qiskit.qobj.PulseQobjInstruction "qiskit.qobj.PulseQobjInstruction")) – The sequence for the Command +* **kwargs** – Optional additional fields + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new Command object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the `Command` to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.Command.to_dict "qiskit.providers.models.Command.to_dict"). + +**Returns** + +The `Command` from the input dictionary. + +**Return type** + +[Command](#qiskit.providers.models.Command "qiskit.providers.models.Command") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Command. + +**Returns** + +The dictionary form of the Command. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.GateConfig.md b/docs/api/qiskit/0.46/qiskit.providers.models.GateConfig.md new file mode 100644 index 00000000000..4ddad930d1d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.GateConfig.md @@ -0,0 +1,86 @@ +--- +title: GateConfig +description: API reference for qiskit.providers.models.GateConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.GateConfig +--- + +# GateConfig + + + +`qiskit.providers.models.GateConfig(name, parameters, qasm_def, coupling_map=None, latency_map=None, conditional=None, description=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendconfiguration.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing a Gate Configuration + + + +### name + +the gate name as it will be referred to in OpenQASM. + + + +### parameters + +variable names for the gate parameters (if any). + + + +### qasm\_def + +definition of this gate in terms of OpenQASM 2 primitives U and CX. + +Initialize a GateConfig object + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the gate name as it will be referred to in OpenQASM. +* **parameters** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – variable names for the gate parameters (if any) as a list of strings. +* **qasm\_def** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – definition of this gate in terms of OpenQASM 2 primitives U and CX. +* **coupling\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An optional coupling map for the gate. In the form of a list of lists of integers representing the qubit groupings which are coupled by this gate. +* **latency\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An optional map of latency for the gate. In the the form of a list of lists of integers of either 0 or 1 representing an array of dimension len(coupling\_map) X n\_registers that specifies the register latency (1: fast, 0: slow) conditional operations on the gate +* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optionally specify whether this gate supports conditional operations (true/false). If this is not specified, then the gate inherits the conditional property of the backend. +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Description of the gate operation + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new GateConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the GateConfig to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.GateConfig.to_dict "qiskit.providers.models.GateConfig.to_dict"). + +**Returns** + +The GateConfig from the input dictionary. + +**Return type** + +[GateConfig](#qiskit.providers.models.GateConfig "qiskit.providers.models.GateConfig") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the GateConfig. + +**Returns** + +The dictionary form of the GateConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.GateProperties.md b/docs/api/qiskit/0.46/qiskit.providers.models.GateProperties.md new file mode 100644 index 00000000000..3fa85cb86c5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.GateProperties.md @@ -0,0 +1,83 @@ +--- +title: GateProperties +description: API reference for qiskit.providers.models.GateProperties +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.GateProperties +--- + +# GateProperties + + + +`qiskit.providers.models.GateProperties(qubits, gate, parameters, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendproperties.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing a gate’s properties + + + +### qubits + +qubits. + + + +### gate + +gate. + + + +### parameters + +parameters. + +Initialize a new [`GateProperties`](#qiskit.providers.models.GateProperties "qiskit.providers.models.GateProperties") object + +**Parameters** + +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of integers representing qubits +* **gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The gates name +* **parameters** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of [`Nduv`](qiskit.providers.models.Nduv "qiskit.providers.models.Nduv") objects for the name-date-unit-value for the gate +* **kwargs** – Optional additional fields + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new Gate object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the Gate to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.GateProperties.to_dict "qiskit.providers.models.GateProperties.to_dict"). + +**Returns** + +The Nduv from the input dictionary. + +**Return type** + +[GateProperties](#qiskit.providers.models.GateProperties "qiskit.providers.models.GateProperties") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the BackendStatus. + +**Returns** + +The dictionary form of the Gate. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.JobStatus.md b/docs/api/qiskit/0.46/qiskit.providers.models.JobStatus.md new file mode 100644 index 00000000000..55c464b936b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.JobStatus.md @@ -0,0 +1,86 @@ +--- +title: JobStatus +description: API reference for qiskit.providers.models.JobStatus +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.JobStatus +--- + +# JobStatus + + + +`qiskit.providers.models.JobStatus(job_id, status, status_msg, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/jobstatus.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Model for JobStatus. + + + +### job\_id + +backend job\_id. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + + + +### status + +status of the job. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + + + +### status\_msg + +status message. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new JobStatus object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the JobStatus to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.JobStatus.to_dict "qiskit.providers.models.JobStatus.to_dict"). + +**Returns** + +The `JobStatus` from the input dictionary. + +**Return type** + +[JobStatus](#qiskit.providers.models.JobStatus "qiskit.providers.models.JobStatus") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the JobStatus. + +**Returns** + +The dictionary form of the JobStatus. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.Nduv.md b/docs/api/qiskit/0.46/qiskit.providers.models.Nduv.md new file mode 100644 index 00000000000..2465fedf57e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.Nduv.md @@ -0,0 +1,89 @@ +--- +title: Nduv +description: API reference for qiskit.providers.models.Nduv +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.Nduv +--- + +# Nduv + + + +`qiskit.providers.models.Nduv(date, name, unit, value)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendproperties.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing name-date-unit-value + + + +### date + +date. + + + +### name + +name. + + + +### unit + +unit. + + + +### value + +value. + +Initialize a new name-date-unit-value object + +**Parameters** + +* **date** ([*datetime.datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")) – Date field +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name field +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Nduv unit +* **value** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The value of the Nduv + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new Nduv object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the Nduv to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.Nduv.to_dict "qiskit.providers.models.Nduv.to_dict"). + +**Returns** + +The Nduv from the input dictionary. + +**Return type** + +[Nduv](#qiskit.providers.models.Nduv "qiskit.providers.models.Nduv") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the object. + +**Returns** + +The dictionary form of the Nduv. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.PulseBackendConfiguration.md b/docs/api/qiskit/0.46/qiskit.providers.models.PulseBackendConfiguration.md new file mode 100644 index 00000000000..545750b3068 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.PulseBackendConfiguration.md @@ -0,0 +1,284 @@ +--- +title: PulseBackendConfiguration +description: API reference for qiskit.providers.models.PulseBackendConfiguration +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.PulseBackendConfiguration +--- + +# PulseBackendConfiguration + + + +`qiskit.providers.models.PulseBackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, n_uchannels, u_channel_lo, meas_levels, qubit_lo_range, meas_lo_range, dt, dtm, rep_times, meas_kernels, discriminators, hamiltonian=None, channel_bandwidth=None, acquisition_latency=None, conditional_latency=None, meas_map=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, channels=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendconfiguration.py "view source code") + +Bases: [`QasmBackendConfiguration`](qiskit.providers.models.QasmBackendConfiguration "qiskit.providers.models.backendconfiguration.QasmBackendConfiguration") + +Static configuration state for an OpenPulse enabled backend. This contains information about the set up of the device which can be useful for building Pulse programs. + +Initialize a backend configuration that contains all the extra configuration that is made available for OpenPulse backends. + +**Parameters** + +* **backend\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – backend name. +* **backend\_version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – backend version in the form X.Y.Z. +* **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **basis\_gates** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – list of basis gates names on the backend. +* **gates** ([*GateConfig*](qiskit.providers.models.GateConfig "qiskit.providers.models.backendconfiguration.GateConfig")) – list of basis gates on the backend. +* **local** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – backend is local or remote. +* **simulator** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – backend is a simulator. +* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – backend supports conditional operations. +* **open\_pulse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – backend supports open pulse. +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – backend supports memory. +* **max\_shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – maximum number of shots supported. +* **coupling\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The coupling map for the device +* **n\_uchannels** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of u-channels. +* **u\_channel\_lo** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*UchannelLO*](qiskit.providers.models.UchannelLO "qiskit.providers.models.backendconfiguration.UchannelLO")*]]*) – U-channel relationship on device los. +* **meas\_levels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Supported measurement levels. +* **qubit\_lo\_range** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – Qubit lo ranges for each qubit with form (min, max) in GHz. +* **meas\_lo\_range** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]]*) – Measurement lo ranges for each qubit with form (min, max) in GHz. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Qubit drive channel timestep in nanoseconds. +* **dtm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Measurement drive channel timestep in nanoseconds. +* **rep\_times** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – Supported repetition times (program execution time) for backend in μs. +* **meas\_kernels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Supported measurement kernels. +* **discriminators** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Supported discriminators. +* **hamiltonian** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*]*) – An optional dictionary with fields characterizing the system hamiltonian. +* **channel\_bandwidth** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Bandwidth of all channels (qubit, measurement, and U) +* **acquisition\_latency** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. +* **conditional\_latency** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m +* **meas\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Grouping of measurement which are multiplexed +* **max\_experiments** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of experiments per job +* **sample\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Sample name for the backend +* **n\_registers** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of register slots available for feedback (if conditional is True) +* **register\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. +* **configurable** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is configurable, if the backend is a simulator +* **credits\_required** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if backend requires credits to run a job. +* **online\_date** ([*datetime.datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")) – The date that the device went online +* **display\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Alternate name field for the backend +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A description for the backend +* **tags** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of string tags to describe the backend +* **channels** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*]*) – An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. +* **\*\*kwargs** – Optional fields. + +## Attributes + + + +### control\_channels + +Return the control channels + + + +### num\_qubits + +Returns the number of qubits. + +In future, n\_qubits should be replaced in favor of num\_qubits for consistent use throughout Qiskit. Until this is properly refactored, this property serves as intermediate solution. + + + +### sample\_rate + +Sample rate of the signal channels in Hz (1/dt). + +## Methods + +### acquire + + + +`acquire(qubit)` + +Return the acquisition channel for the given qubit. + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If the qubit is not a part of the system. + +**Returns** + +Qubit measurement acquisition line. + +**Return type** + +[*AcquireChannel*](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") + +### control + + + +`control(qubits=None)` + +Return the secondary drive channel for the given qubit – typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + +**Parameters** + +**qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Tuple or list of qubits of the form (control\_qubit, target\_qubit). + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If the `qubits` is not a part of the system or if the backend does not provide channels information in its configuration. + +**Returns** + +List of control channels. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*ControlChannel*](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")] + +### describe + + + +`describe(channel)` + +Return a basic description of the channel dependency. Derived channels are given weights which describe how their frames are linked to other frames. For instance, the backend could be configured with this setting: + +```python +u_channel_lo = [ + [UchannelLO(q=0, scale=1. + 0.j)], + [UchannelLO(q=0, scale=-1. + 0.j), UchannelLO(q=1, scale=1. + 0.j)] +] +``` + +Then, this method can be used as follows: + +```python +backend.configuration().describe(ControlChannel(1)) +>>> {DriveChannel(0): -1, DriveChannel(1): 1} +``` + +**Parameters** + +**channel** ([*ControlChannel*](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel")) – The derived channel to describe. + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If channel is not a ControlChannel. + +**Returns** + +Control channel derivations. + +**Return type** + +[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[*DriveChannel*](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel"), [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")] + +### drive + + + +`drive(qubit)` + +Return the drive channel for the given qubit. + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If the qubit is not a part of the system. + +**Returns** + +Qubit drive channel. + +**Return type** + +[*DriveChannel*](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new GateConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the GateConfig to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.PulseBackendConfiguration.to_dict "qiskit.providers.models.PulseBackendConfiguration.to_dict"). + +**Returns** + +The GateConfig from the input dictionary. + +**Return type** + +[GateConfig](qiskit.providers.models.GateConfig "qiskit.providers.models.GateConfig") + +### get\_channel\_qubits + + + +`get_channel_qubits(channel)` + +Return a list of indices for qubits which are operated on directly by the given `channel`. + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If `channel` is not a found or if the backend does not provide channels information in its configuration. + +**Returns** + +List of qubits operated on my the given `channel`. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### get\_qubit\_channels + + + +`get_qubit_channels(qubit)` + +Return a list of channels which operate on the given `qubit`. + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If `qubit` is not a found or if the backend does not provide channels information in its configuration. + +**Returns** + +List of `Channel`s operated on my the given `qubit`. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")] + +### measure + + + +`measure(qubit)` + +Return the measure stimulus channel for the given qubit. + +**Raises** + +[**BackendConfigurationError**](providers#qiskit.providers.BackendConfigurationError "qiskit.providers.BackendConfigurationError") – If the qubit is not a part of the system. + +**Returns** + +Qubit measurement stimulus line. + +**Return type** + +[*MeasureChannel*](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the GateConfig. + +**Returns** + +The dictionary form of the GateConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.PulseDefaults.md b/docs/api/qiskit/0.46/qiskit.providers.models.PulseDefaults.md new file mode 100644 index 00000000000..f17521e10fa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.PulseDefaults.md @@ -0,0 +1,64 @@ +--- +title: PulseDefaults +description: API reference for qiskit.providers.models.PulseDefaults +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.PulseDefaults +--- + +# PulseDefaults + + + +`qiskit.providers.models.PulseDefaults(qubit_freq_est, meas_freq_est, buffer, pulse_library, cmd_def, meas_kernel=None, discriminator=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/pulsedefaults.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Description of default settings for Pulse systems. These are instructions or settings that may be good starting points for the Pulse user. The user may modify these defaults for custom scheduling. + +Validate and reformat transport layer inputs to initialize. :param qubit\_freq\_est: Estimated qubit frequencies in GHz. :param meas\_freq\_est: Estimated measurement cavity frequencies in GHz. :param buffer: Default buffer time (in units of dt) between pulses. :param pulse\_library: Pulse name and sample definitions. :param cmd\_def: Operation name and definition in terms of Commands. :param meas\_kernel: The measurement kernels :param discriminator: The discriminators :param \*\*kwargs: Other attributes for the super class. + +## Attributes + + + +### qubit\_freq\_est + +Qubit frequencies in Hertz. + + + +### meas\_freq\_est + +Measurement frequencies in Hertz. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new PulseDefaults object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the PulseDefaults to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.PulseDefaults.to_dict "qiskit.providers.models.PulseDefaults.to_dict"). + +**Returns** + +The PulseDefaults from the input dictionary. + +**Return type** + +[PulseDefaults](#qiskit.providers.models.PulseDefaults "qiskit.providers.models.PulseDefaults") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the PulseDefaults. :returns: The dictionary form of the PulseDefaults. :rtype: dict + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.QasmBackendConfiguration.md b/docs/api/qiskit/0.46/qiskit.providers.models.QasmBackendConfiguration.md new file mode 100644 index 00000000000..83aa9a1c171 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.QasmBackendConfiguration.md @@ -0,0 +1,204 @@ +--- +title: QasmBackendConfiguration +description: API reference for qiskit.providers.models.QasmBackendConfiguration +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.QasmBackendConfiguration +--- + +# QasmBackendConfiguration + + + +`qiskit.providers.models.QasmBackendConfiguration(backend_name, backend_version, n_qubits, basis_gates, gates, local, simulator, conditional, open_pulse, memory, max_shots, coupling_map, supported_instructions=None, dynamic_reprate_enabled=False, rep_delay_range=None, default_rep_delay=None, max_experiments=None, sample_name=None, n_registers=None, register_map=None, configurable=None, credits_required=None, online_date=None, display_name=None, description=None, tags=None, dt=None, dtm=None, processor_type=None, parametric_pulses=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendconfiguration.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing an OpenQASM 2.0 Backend Configuration. + + + +### backend\_name + +backend name. + + + +### backend\_version + +backend version in the form X.Y.Z. + + + +### n\_qubits + +number of qubits. + + + +### basis\_gates + +list of basis gates names on the backend. + + + +### gates + +list of basis gates on the backend. + + + +### local + +backend is local or remote. + + + +### simulator + +backend is a simulator. + + + +### conditional + +backend supports conditional operations. + + + +### open\_pulse + +backend supports open pulse. + + + +### memory + +backend supports memory. + + + +### max\_shots + +maximum number of shots supported. + +Initialize a QasmBackendConfiguration Object + +**Parameters** + +* **backend\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The backend name + +* **backend\_version** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The backend version in the form X.Y.Z + +* **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits for the backend + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The list of strings for the basis gates of the backends + +* **gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The list of GateConfig objects for the basis gates of the backend + +* **local** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is local or False if remote + +* **simulator** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is a simulator + +* **conditional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend supports conditional operations + +* **open\_pulse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend supports OpenPulse + +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend supports memory + +* **max\_shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of shots allowed on the backend + +* **coupling\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The coupling map for the device + +* **supported\_instructions** (*List\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Instructions supported by the backend. + +* **dynamic\_reprate\_enabled** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. + +* **rep\_delay\_range** (*List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. + +* **default\_rep\_delay** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. + +* **max\_experiments** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of experiments per job + +* **sample\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Sample name for the backend + +* **n\_registers** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of register slots available for feedback (if conditional is True) + +* **register\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. + +* **configurable** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if the backend is configurable, if the backend is a simulator + +* **credits\_required** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – True if backend requires credits to run a job. + +* **online\_date** ([*datetime.datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.12)")) – The date that the device went online + +* **display\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Alternate name field for the backend + +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A description for the backend + +* **tags** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of string tags to describe the backend + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Qubit drive channel timestep in nanoseconds. + +* **dtm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Measurement drive channel timestep in nanoseconds. + +* **processor\_type** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. + + * family: Processor family of this backend. + * revision: Revision version of this processor. + * segment: Segment this processor belongs to within a larger chip. + +* **parametric\_pulses** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` + +* **\*\*kwargs** – optional fields + +## Attributes + + + +### num\_qubits + +Returns the number of qubits. + +In future, n\_qubits should be replaced in favor of num\_qubits for consistent use throughout Qiskit. Until this is properly refactored, this property serves as intermediate solution. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new GateConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the GateConfig to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.QasmBackendConfiguration.to_dict "qiskit.providers.models.QasmBackendConfiguration.to_dict"). + +**Returns** + +The GateConfig from the input dictionary. + +**Return type** + +[GateConfig](qiskit.providers.models.GateConfig "qiskit.providers.models.GateConfig") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the GateConfig. + +**Returns** + +The dictionary form of the GateConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.providers.models.UchannelLO.md b/docs/api/qiskit/0.46/qiskit.providers.models.UchannelLO.md new file mode 100644 index 00000000000..a3cca3b3fd0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.providers.models.UchannelLO.md @@ -0,0 +1,79 @@ +--- +title: UchannelLO +description: API reference for qiskit.providers.models.UchannelLO +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.providers.models.UchannelLO +--- + +# UchannelLO + + + +`qiskit.providers.models.UchannelLO(q, scale)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/providers/models/backendconfiguration.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class representing a U Channel LO + + + +### q + +Qubit that scale corresponds too. + + + +### scale + +Scale factor for qubit frequency. + +Initialize a UchannelLOSchema object + +**Parameters** + +* **q** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Qubit that scale corresponds too. Must be >= 0. +* **scale** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Scale factor for qubit frequency. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If q is \< 0 + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new UchannelLO object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the UChannelLO to create. It will be in the same format as output by [`to_dict()`](#qiskit.providers.models.UchannelLO.to_dict "qiskit.providers.models.UchannelLO.to_dict"). + +**Returns** + +The UchannelLO from the input dictionary. + +**Return type** + +[UchannelLO](#qiskit.providers.models.UchannelLO "qiskit.providers.models.UchannelLO") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the UChannelLO. + +**Returns** + +The dictionary form of the UChannelLO. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.InstructionScheduleMap.md b/docs/api/qiskit/0.46/qiskit.pulse.InstructionScheduleMap.md new file mode 100644 index 00000000000..3653fa35d41 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.InstructionScheduleMap.md @@ -0,0 +1,241 @@ +--- +title: InstructionScheduleMap +description: API reference for qiskit.pulse.InstructionScheduleMap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.InstructionScheduleMap +--- + +# InstructionScheduleMap + + + +`qiskit.pulse.InstructionScheduleMap`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instruction_schedule_map.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Mapping from [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") [`qiskit.circuit.Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") names and qubits to [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") s. In particular, the mapping is formatted as type: + +```python +Dict[str, Dict[Tuple[int], Schedule]] +``` + +where the first key is the name of a circuit instruction (e.g. `'u1'`, `'measure'`), the second key is a tuple of qubit indices, and the final value is a Schedule implementing the requested instruction. + +These can usually be seen as gate calibrations. + +Initialize a circuit instruction to schedule mapper instance. + +## Attributes + + + +### instructions + +Return all instructions which have definitions. + +By default, these are typically the basis gates along with other instructions such as measure and reset. + +**Returns** + +The names of all the circuit instructions which have Schedule definitions in this. + +## Methods + +### add + + + +`add(instruction, qubits, schedule, arguments=None)` + +Add a new known instruction for the given qubits and its mapping to a pulse schedule. + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – The name of the instruction to add. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits which the instruction applies to. +* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[...],* [*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")*]*) – The Schedule that implements the given instruction. +* **arguments** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – List of parameter names to create a parameter-bound schedule from the associated gate instruction. If [`get()`](#qiskit.pulse.InstructionScheduleMap.get "qiskit.pulse.InstructionScheduleMap.get") is called with arguments rather than keyword arguments, this parameter list is used to map the input arguments to parameter objects stored in the target schedule. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the qubits are provided as an empty iterable. + +### assert\_has + + + +`assert_has(instruction, qubits)` + +Error if the given instruction is not defined. + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – The instruction for which to look. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The specific qubits for the instruction. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the instruction is not defined on the qubits. + +### get + + + +`get(instruction, qubits, *params, **kwparams)` + +Return the defined [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") for the given instruction on the given qubits. + +If all keys are not specified this method returns schedule with unbound parameters. + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Name of the instruction or the instruction itself. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits for the instruction. +* **\*params** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Command parameters for generating the output schedule. +* **\*\*kwparams** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Keyworded command parameters for generating the schedule. + +**Returns** + +The Schedule defined for the input. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### get\_parameters + + + +`get_parameters(instruction, qubits)` + +Return the list of parameters taken by the given instruction on the given qubits. + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Name of the instruction. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits for the instruction. + +**Returns** + +The names of the parameters required by the instruction. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### has + + + +`has(instruction, qubits)` + +Is the instruction defined for the given qubits? + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – The instruction for which to look. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The specific qubits for the instruction. + +**Returns** + +True iff the instruction is defined. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### has\_custom\_gate + + + +`has_custom_gate()` + +Return `True` if the map has user provided instruction. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### pop + + + +`pop(instruction, qubits, *params, **kwparams)` + +Remove and return the defined schedule for the given instruction on the given qubits. + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Name of the instruction. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits for the instruction. +* **\*params** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Command parameters for generating the output schedule. +* **\*\*kwparams** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Keyworded command parameters for generating the schedule. + +**Returns** + +The Schedule defined for the input. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### qubit\_instructions + + + +`qubit_instructions(qubits)` + +Return a list of the instruction names that are defined by the backend for the given qubit or qubits. + +**Parameters** + +**qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – A qubit index, or a list or tuple of indices. + +**Returns** + +All the instructions which are defined on the qubits. + +For 1 qubit, all the 1Q instructions defined. For multiple qubits, all the instructions which apply to that whole set of qubits (e.g. `qubits=[0, 1]` may return `['cx']`). + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### qubits\_with\_instruction + + + +`qubits_with_instruction(instruction)` + +Return a list of the qubits for which the given instruction is defined. Single qubit instructions return a flat list, and multiqubit instructions return a list of ordered tuples. + +**Parameters** + +**instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – The name of the circuit instruction. + +**Returns** + +Qubit indices which have the given instruction defined. This is a list of tuples if the instruction has an arity greater than 1, or a flat list of ints otherwise. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the instruction is not found. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") | [*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] + +### remove + + + +`remove(instruction, qubits)` + +Remove the given instruction from the listing of instructions defined in self. + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – The name of the instruction to add. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The qubits which the instruction applies to. + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.Schedule.md b/docs/api/qiskit/0.46/qiskit.pulse.Schedule.md new file mode 100644 index 00000000000..f7282caf622 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.Schedule.md @@ -0,0 +1,498 @@ +--- +title: Schedule +description: API reference for qiskit.pulse.Schedule +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.Schedule +--- + +# Schedule + + + +`qiskit.pulse.Schedule(*schedules, name=None, metadata=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/schedule.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A quantum program *schedule* with exact time constraints for its instructions, operating over all input signal *channels* and supporting special syntaxes for building. + +Pulse program representation for the original Qiskit Pulse model \[1]. Instructions are not allowed to overlap in time on the same channel. This overlap constraint is immediately evaluated when a new instruction is added to the `Schedule` object. + +It is necessary to specify the absolute start time and duration for each instruction so as to deterministically fix its execution time. + +The `Schedule` program supports some syntax sugar for easier programming. + +* Appending an instruction to the end of a channel + + ```python + sched = Schedule() + sched += Play(Gaussian(160, 0.1, 40), DriveChannel(0)) + ``` + +* Appending an instruction shifted in time by a given amount + + ```python + sched = Schedule() + sched += Play(Gaussian(160, 0.1, 40), DriveChannel(0)) << 30 + ``` + +* Merge two schedules + + ```python + sched1 = Schedule() + sched1 += Play(Gaussian(160, 0.1, 40), DriveChannel(0)) + + sched2 = Schedule() + sched2 += Play(Gaussian(160, 0.1, 40), DriveChannel(1)) + sched2 = sched1 | sched2 + ``` + +A [`PulseError`](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") is immediately raised when the overlap constraint is violated. + +In the schedule representation, we cannot parametrize the duration of instructions. Thus we need to create a new schedule object for each duration. To parametrize an instruction’s duration, the [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") representation may be used instead. + +**References** + +\[1]: [https://arxiv.org/abs/2004.06755](https://arxiv.org/abs/2004.06755) + +Create an empty schedule. + +**Parameters** + +* **\*schedules** (*ScheduleComponent |* [*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, ScheduleComponent]*) – Child Schedules of this parent Schedule. May either be passed as the list of schedules, or a list of `(start_time, schedule)` pairs. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of this schedule. Defaults to an autogenerated string if not provided. +* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Arbitrary key value metadata to associate with the schedule. This gets stored as free-form data in a dict in the [`metadata`](#qiskit.pulse.Schedule.metadata "qiskit.pulse.Schedule.metadata") attribute. It will not be directly used in the schedule. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – if metadata is not a dict. + +## Attributes + + + +### channels + +Returns channels that this schedule uses. + + + +### children + +Return the child schedule components of this `Schedule` in the order they were added to the schedule. + +**Notes** + +Nested schedules are returned as-is. If you want to collect only instructions, use py:meth:\~Schedule.instructions instead. + +**Returns** + +A tuple, where each element is a two-tuple containing the initial scheduled time of each `NamedValue` and the component itself. + + + +### duration + +Duration of this schedule. + + + +### instances\_counter + +`= count(0)` + + + +### instructions + +Get the time-ordered instructions from self. + + + +### metadata + +The user provided metadata associated with the schedule. + +User provided `dict` of metadata for the schedule. The metadata contents do not affect the semantics of the program but are used to influence the execution of the schedule. It is expected to be passed between all transforms of the schedule and that providers will associate any schedule metadata with the results it returns from the execution of that schedule. + + + +### name + +Name of this Schedule + + + +### parameters + +Parameters which determine the schedule behavior. + + + +### prefix + +`= 'sched'` + + + +### start\_time + +Starting time of this schedule. + + + +### stop\_time + +Stopping time of this schedule. + + + +### timeslots + +Time keeping attribute. + +## Methods + +### append + + + +`append(schedule, name=None, inplace=False)` + +Return a new schedule with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +$$ +t = \textrm{max}(\texttt{x.stop_time} |\texttt{x} \in + \texttt{self.channels} \cap \texttt{schedule.channels}) +$$ + +**Parameters** + +* **schedule** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule to be appended. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new `Schedule`. Defaults to name of `self`. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise return a new `Schedule`. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### assign\_parameters + + + +`assign_parameters(value_dict, inplace=True)` + +Assign the parameters in this schedule according to the input. + +**Parameters** + +* **value\_dict** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – A mapping from Parameters to either numeric values or another Parameter expression. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set `True` to override this instance with new parameter. + +**Returns** + +Schedule with updated parameters. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return the time of the end of the last instruction over the supplied channels. + +**Parameters** + +**\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return the time of the start of the first instruction over the supplied channels. + +**Parameters** + +**\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time over supplied channels. + +**Parameters** + +**\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(style=None, backend=None, time_range=None, time_unit='dt', disable_channels=None, show_snapshot=True, show_framechange=True, show_waveform_info=True, show_barrier=True, plotter='mpl2d', axis=None)` + +Plot the schedule. + +**Parameters** + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. + +* **backend** (*Optional\[BaseBackend]*) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple (tmin, tmax). + +* **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either dt or ns. The unit of ns is available only when backend object is provided. + +* **disable\_channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A control property to show specific pulse channel. Pulse channel instances provided as a list are not shown in the output image. + +* **show\_snapshot** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show snapshot instructions. + +* **show\_framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show frame change instructions. The frame change represents instructions that modulate phase or frequency of pulse channels. + +* **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show additional information about waveforms such as their name. + +* **show\_barrier** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show barrier lines. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl2d: Matplotlib API for 2D image generation. + Matplotlib API to generate 2D image. Charts are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as ``axis`` input. + ``` + + `axis` and `style` kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given `axis` instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details. + +**Returns** + +Visualization output data. The returned data type depends on the `plotter`. If matplotlib family is specified, this will be a `matplotlib.pyplot.Figure` data. + +### exclude + + + +`exclude(*filter_funcs, channels=None, instruction_types=None, time_ranges=None, intervals=None, check_subroutine=True)` + +Return a `Schedule` with only the instructions from this Schedule *failing* at least one of the provided filters. This method is the complement of py:meth:\~self.filter, so that: + +```python +self.filter(args) | self.exclude(args) == self +``` + +**Parameters** + +* **filter\_funcs** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")) – A list of Callables which take a (int, Union\[‘Schedule’, Instruction]) tuple and return a bool. +* **channels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – For example, `[DriveChannel(0), AcquireChannel(0)]`. +* **instruction\_types** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")*] |* [*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)") *| None*) – For example, `[PulseInstruction, AcquireInstruction]`. +* **time\_ranges** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – For example, `[(0, 5), (6, 10)]`. +* **intervals** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – For example, `[(0, 5), (6, 10)]`. +* **check\_subroutine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to individually filter instructions inside of a subroutine defined by the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### filter + + + +`filter(*filter_funcs, channels=None, instruction_types=None, time_ranges=None, intervals=None, check_subroutine=True)` + +Return a new `Schedule` with only the instructions from this `Schedule` which pass though the provided filters; i.e. an instruction will be retained iff every function in `filter_funcs` returns `True`, the instruction occurs on a channel type contained in `channels`, the instruction type is contained in `instruction_types`, and the period over which the instruction operates is *fully* contained in one specified in `time_ranges` or `intervals`. + +If no arguments are provided, `self` is returned. + +**Parameters** + +* **filter\_funcs** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")) – A list of Callables which take a (int, Union\[‘Schedule’, Instruction]) tuple and return a bool. +* **channels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – For example, `[DriveChannel(0), AcquireChannel(0)]`. +* **instruction\_types** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")*] |* [*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)") *| None*) – For example, `[PulseInstruction, AcquireInstruction]`. +* **time\_ranges** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – For example, `[(0, 5), (6, 10)]`. +* **intervals** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – For example, `[(0, 5), (6, 10)]`. +* **check\_subroutine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to individually filter instructions inside of a subroutine defined by the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### get\_parameters + + + +`get_parameters(parameter_name)` + +Get parameter object bound to this schedule by string name. + +Because different `Parameter` objects can have the same name, this method returns a list of `Parameter` s for the provided name. + +**Parameters** + +**parameter\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of parameter. + +**Returns** + +Parameter objects that have corresponding name. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")] + +### initialize\_from + + + +`classmethod initialize_from(other_program, name=None)` + +Create new schedule object with metadata of another schedule object. + +**Parameters** + +* **other\_program** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit program that provides metadata to new object. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of new schedule. Name of `schedule` is used by default. + +**Returns** + +New schedule object with name and metadata. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When other\_program does not provide necessary information. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### insert + + + +`insert(start_time, schedule, name=None, inplace=False)` + +Return a new schedule with `schedule` inserted into `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule. +* **schedule** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule to insert. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to the name of self. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise return a new `Schedule`. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### replace + + + +`replace(old, new, inplace=False)` + +Return a `Schedule` with the `old` instruction replaced with a `new` instruction. + +The replacement matching is based on an instruction equality check. + +```python +from qiskit import pulse + +d0 = pulse.DriveChannel(0) + +sched = pulse.Schedule() + +old = pulse.Play(pulse.Constant(100, 1.0), d0) +new = pulse.Play(pulse.Constant(100, 0.1), d0) + +sched += old + +sched = sched.replace(old, new) + +assert sched == pulse.Schedule(new) +``` + +Only matches at the top-level of the schedule tree. If you wish to perform this replacement over all instructions in the schedule tree. Flatten the schedule prior to running: + +```python +.. code-block:: +``` + +> sched = pulse.Schedule() +> +> sched += pulse.Schedule(old) +> +> sched = sched.flatten() +> +> sched = sched.replace(old, new) +> +> assert sched == pulse.Schedule(new) + +**Parameters** + +* **old** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Instruction to replace. +* **new** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Instruction to replace with. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Replace instruction by mutably modifying this `Schedule`. + +**Returns** + +The modified schedule with `old` replaced by `new`. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the `Schedule` after replacements will has a timing overlap. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### shift + + + +`shift(time, name=None, inplace=False)` + +Return a schedule shifted forward by `time`. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to the name of self. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise return a new `Schedule`. + +**Return type** + +[*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.ScheduleBlock.md b/docs/api/qiskit/0.46/qiskit.pulse.ScheduleBlock.md new file mode 100644 index 00000000000..4308af5ceb9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.ScheduleBlock.md @@ -0,0 +1,662 @@ +--- +title: ScheduleBlock +description: API reference for qiskit.pulse.ScheduleBlock +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.ScheduleBlock +--- + +# ScheduleBlock + + + +`qiskit.pulse.ScheduleBlock(name=None, metadata=None, alignment_context=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/schedule.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Time-ordered sequence of instructions with alignment context. + +[`ScheduleBlock`](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") supports lazy scheduling of context instructions, i.e. their timeslots is always generated at runtime. This indicates we can parametrize instruction durations as well as other parameters. In contrast to [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") being somewhat static, [`ScheduleBlock`](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") is a dynamic representation of a pulse program. + +**Pulse Builder** + +The Qiskit pulse builder is a domain specific language that is developed on top of the schedule block. Use of the builder syntax will improve the workflow of pulse programming. See [Pulse Builder](pulse#pulse-builder) for a user guide. + +**Alignment contexts** + +A schedule block is always relatively scheduled. Instead of taking individual instructions with absolute execution time `t0`, the schedule block defines a context of scheduling and instructions under the same context are scheduled in the same manner (alignment). Several contexts are available in [Alignments](pulse#pulse-alignments). A schedule block is instantiated with one of these alignment contexts. The default context is `AlignLeft`, for which all instructions are left-justified, in other words, meaning they use as-soon-as-possible scheduling. + +If you need an absolute-time interval in between instructions, you can explicitly insert [`Delay`](qiskit.pulse.instructions.Delay "qiskit.pulse.instructions.Delay") instructions. + +**Nested blocks** + +A schedule block can contain other nested blocks with different alignment contexts. This enables advanced scheduling, where a subset of instructions is locally scheduled in a different manner. Note that a [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") instance cannot be directly added to a schedule block. To add a [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") instance, wrap it in a [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction. This is implicitly performed when a schedule is added through the [Pulse Builder](pulse#pulse-builder). + +**Unsupported operations** + +Because the schedule block representation lacks timeslots, it cannot perform particular [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") operations such as `insert()` or `shift()` that require instruction start time `t0`. In addition, [`exclude()`](#qiskit.pulse.ScheduleBlock.exclude "qiskit.pulse.ScheduleBlock.exclude") and [`filter()`](#qiskit.pulse.ScheduleBlock.filter "qiskit.pulse.ScheduleBlock.filter") methods are not supported because these operations may identify the target instruction with `t0`. Except for these operations, [`ScheduleBlock`](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") provides full compatibility with [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"). + +**Subroutine** + +The timeslots-free representation offers much greater flexibility for writing pulse programs. Because [`ScheduleBlock`](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") only cares about the ordering of the child blocks we can add an undefined pulse sequence as a subroutine of the main program. If your program contains the same sequence multiple times, this representation may reduce the memory footprint required by the program construction. Such a subroutine is realized by the special compiler directive [`Reference`](qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference") that is defined by a unique set of reference key strings to the subroutine. The (executable) subroutine is separately stored in the main program. Appended reference directives are resolved when the main program is executed. Subroutines must be assigned through [`assign_references()`](#qiskit.pulse.ScheduleBlock.assign_references "qiskit.pulse.ScheduleBlock.assign_references") before execution. + +**Program Scoping** + + + The [`scoped_parameters()`](#qiskit.pulse.ScheduleBlock.scoped_parameters "qiskit.pulse.ScheduleBlock.scoped_parameters") and [`search_parameters()`](#qiskit.pulse.ScheduleBlock.search_parameters "qiskit.pulse.ScheduleBlock.search_parameters") methods described in this section are deprecated. + + +When you call a subroutine from another subroutine, or append a schedule block to another schedule block, the management of references and parameters can be a hard task. Schedule block offers a convenient feature to help with this by automatically scoping the parameters and subroutines. + +```python +from qiskit import pulse +from qiskit.circuit.parameter import Parameter + +amp1 = Parameter("amp") + +with pulse.build() as sched1: + pulse.play(pulse.Constant(100, amp1), pulse.DriveChannel(0)) + +print(sched1.scoped_parameters()) +``` + +```python +(Parameter(root::amp),) +``` + +The [`scoped_parameters()`](#qiskit.pulse.ScheduleBlock.scoped_parameters "qiskit.pulse.ScheduleBlock.scoped_parameters") method returns all [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects defined in the schedule block. The parameter name is updated to reflect its scope information, i.e. where it is defined. The outer scope is called “root”. Since the “amp” parameter is directly used in the current builder context, it is prefixed with “root”. Note that the `Parameter` object returned by [`scoped_parameters()`](#qiskit.pulse.ScheduleBlock.scoped_parameters "qiskit.pulse.ScheduleBlock.scoped_parameters") preserves the hidden [UUID](https://docs.python.org/3/library/uuid.html#module-uuid) key, and thus the scoped name doesn’t break references to the original `Parameter`. + +You may want to call this program from another program. In this example, the program is called with the reference key “grand\_child”. You can call a subroutine without specifying a substantial program (like `sched1` above which we will assign later). + +```python +amp2 = Parameter("amp") + +with pulse.build() as sched2: + with pulse.align_right(): + pulse.reference("grand_child") + pulse.play(pulse.Constant(200, amp2), pulse.DriveChannel(0)) + +print(sched2.scoped_parameters()) +``` + +```python +(Parameter(root::amp),) +``` + +This only returns “root::amp” because the “grand\_child” reference is unknown. Now you assign the actual pulse program to this reference. + +```python +sched2.assign_references({("grand_child", ): sched1}) +print(sched2.scoped_parameters()) +``` + +```python +(Parameter(root::amp), Parameter(root::grand_child::amp)) +``` + +Now you get two parameters “root::amp” and “root::grand\_child::amp”. The second parameter name indicates it is defined within the referred program “grand\_child”. The program calling the “grand\_child” has a reference program description which is accessed through [`ScheduleBlock.references`](#qiskit.pulse.ScheduleBlock.references "qiskit.pulse.ScheduleBlock.references"). + +```python +print(sched2.references) +``` + +```python +ReferenceManager: + - ('grand_child',): ScheduleBlock(Play(Constant(duration=100, amp=amp,... +``` + +Finally, you may want to call this program from another program. Here we try a different approach to define subroutine. Namely, we call a subroutine from the root program with the actual program `sched2`. + +```python +amp3 = Parameter("amp") + +with pulse.build() as main: + pulse.play(pulse.Constant(300, amp3), pulse.DriveChannel(0)) + pulse.call(sched2, name="child") + +print(main.scoped_parameters()) +``` + +```python +(Parameter(root::amp), Parameter(root::child::amp), Parameter(root::child::grand_child::amp)) +``` + +This implicitly creates a reference named “child” within the root program and assigns `sched2` to it. You get three parameters “root::amp”, “root::child::amp”, and “root::child::grand\_child::amp”. As you can see, each parameter name reflects the layer of calls from the root program. If you know the scope of a parameter, you can directly get the parameter object using [`ScheduleBlock.search_parameters()`](#qiskit.pulse.ScheduleBlock.search_parameters "qiskit.pulse.ScheduleBlock.search_parameters") as follows. + +```python +main.search_parameters("root::child::grand_child::amp") +``` + +You can use a regular expression to specify the scope. The following returns the parameters defined within the scope of “ground\_child” regardless of its parent scope. This is sometimes convenient if you want to extract parameters from a deeply nested program. + +```python +main.search_parameters("\S::grand_child::amp") +``` + +Note that the root program is only aware of its direct references. + +```python +print(main.references) +``` + +```python +ReferenceManager: + - ('child',): ScheduleBlock(ScheduleBlock(ScheduleBlock(Play(Con... +``` + +As you can see the main program cannot directly assign a subroutine to the “grand\_child” because this subroutine is not called within the root program, i.e. it is indirectly called by “child”. However, the returned `ReferenceManager` is a dict-like object, and you can still reach to “grand\_child” via the “child” program with the following chained dict access. + +```python +main.references[("child", )].references[("grand_child", )] +``` + +Note that [`ScheduleBlock.parameters`](#qiskit.pulse.ScheduleBlock.parameters "qiskit.pulse.ScheduleBlock.parameters") and [`ScheduleBlock.scoped_parameters()`](#qiskit.pulse.ScheduleBlock.scoped_parameters "qiskit.pulse.ScheduleBlock.scoped_parameters") still collect all parameters also from the subroutine once it’s assigned. + +Create an empty schedule block. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of this schedule. Defaults to an autogenerated string if not provided. +* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Arbitrary key value metadata to associate with the schedule. This gets stored as free-form data in a dict in the [`metadata`](#qiskit.pulse.ScheduleBlock.metadata "qiskit.pulse.ScheduleBlock.metadata") attribute. It will not be directly used in the schedule. +* **alignment\_context** ([*AlignmentKind*](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.AlignmentKind")) – `AlignmentKind` instance that manages scheduling of instructions in this block. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – if metadata is not a dict. + +## Attributes + + + +### alignment\_context + +Return alignment instance that allocates block component to generate schedule. + + + +### blocks + +Get the block elements added to self. + + + The sequence of elements is returned in order of addition. Because the first element is schedule first, e.g. FIFO, the returned sequence is roughly time-ordered. However, in the parallel alignment context, especially in the as-late-as-possible scheduling, or [`AlignRight`](qiskit.pulse.transforms.AlignRight "qiskit.pulse.transforms.AlignRight") context, the actual timing of when the instructions are issued is unknown until the [`ScheduleBlock`](#qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") is scheduled and converted into a [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"). + + + + +### channels + +Returns channels that this schedule block uses. + + + +### duration + +Duration of this schedule block. + + + +### instances\_counter + +`= count(0)` + + + +### instructions + +Get the time-ordered instructions from self. + + + +### metadata + +The user provided metadata associated with the schedule. + +User provided `dict` of metadata for the schedule. The metadata contents do not affect the semantics of the program but are used to influence the execution of the schedule. It is expected to be passed between all transforms of the schedule and that providers will associate any schedule metadata with the results it returns from the execution of that schedule. + + + +### name + +Return name of this schedule + + + +### parameters + +Return unassigned parameters with raw names. + + + +### prefix + +`= 'block'` + + + +### references + +Return a reference manager of the current scope. + +## Methods + +### append + + + +`append(block, name=None, inplace=True)` + +Return a new schedule block with `block` appended to the context block. The execution time is automatically assigned when the block is converted into schedule. + +**Parameters** + +* **block** ([*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – ScheduleBlock to be appended. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new `Schedule`. Defaults to name of `self`. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise, return a new `Schedule`. + +**Returns** + +Schedule block with appended schedule. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When invalid schedule type is specified. + +**Return type** + +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### assign\_parameters + + + +`assign_parameters(value_dict, inplace=True)` + +Assign the parameters in this schedule according to the input. + +**Parameters** + +* **value\_dict** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – A mapping from Parameters to either numeric values or another Parameter expression. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set `True` to override this instance with new parameter. + +**Returns** + +Schedule with updated parameters. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When the block is nested into another block. + +**Return type** + +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### assign\_references + + + +`assign_references(subroutine_dict, inplace=True)` + +Assign schedules to references. + +It is only capable of assigning a schedule block to immediate references which are directly referred within the current scope. Let’s see following example: + +```python +from qiskit import pulse + +with pulse.build() as subroutine: + pulse.delay(10, pulse.DriveChannel(0)) + +with pulse.build() as sub_prog: + pulse.reference("A") + +with pulse.build() as main_prog: + pulse.reference("B") +``` + +In above example, the `main_prog` can refer to the subroutine “root::B” and the reference of “B” to program “A”, i.e., “B::A”, is not defined in the root namespace. This prevents breaking the reference “root::B::A” by the assignment of “root::B”. For example, if a user could indirectly assign “root::B::A” from the root program, one can later assign another program to “root::B” that doesn’t contain “A” within it. In this situation, a reference “root::B::A” would still live in the reference manager of the root. However, the subroutine “root::B::A” would no longer be used in the actual pulse program. To assign subroutine “A” to `nested_prog` as a nested subprogram of `main_prog`, you must first assign “A” of the `sub_prog`, and then assign the `sub_prog` to the `main_prog`. + +```python +sub_prog.assign_references({("A", ): nested_prog}, inplace=True) +main_prog.assign_references({("B", ): sub_prog}, inplace=True) +``` + +Alternatively, you can also write + +```python +main_prog.assign_references({("B", ): sub_prog}, inplace=True) +main_prog.references[("B", )].assign_references({"A": nested_prog}, inplace=True) +``` + +Here [`references`](#qiskit.pulse.ScheduleBlock.references "qiskit.pulse.ScheduleBlock.references") returns a dict-like object, and you can mutably update the nested reference of the particular subroutine. + + + Assigned programs are deep-copied to prevent an unexpected update. + + +**Parameters** + +* **subroutine\_dict** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, ...],* [*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")*]*) – A mapping from reference key to schedule block of the subroutine. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set `True` to override this instance with new subroutine. + +**Returns** + +Schedule block with assigned subroutine. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When reference key is not defined in the current scope. + +**Return type** + +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return the time of the end of the last instruction over the supplied channels. + +**Parameters** + +**\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(style=None, backend=None, time_range=None, time_unit='dt', disable_channels=None, show_snapshot=True, show_framechange=True, show_waveform_info=True, show_barrier=True, plotter='mpl2d', axis=None)` + +Plot the schedule. + +**Parameters** + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. + +* **backend** (*Optional\[BaseBackend]*) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple (tmin, tmax). + +* **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either dt or ns. The unit of ns is available only when backend object is provided. + +* **disable\_channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A control property to show specific pulse channel. Pulse channel instances provided as a list are not shown in the output image. + +* **show\_snapshot** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show snapshot instructions. + +* **show\_framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show frame change instructions. The frame change represents instructions that modulate phase or frequency of pulse channels. + +* **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show additional information about waveforms such as their name. + +* **show\_barrier** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show barrier lines. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl2d: Matplotlib API for 2D image generation. + Matplotlib API to generate 2D image. Charts are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as ``axis`` input. + ``` + + `axis` and `style` kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given `axis` instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details. + +**Returns** + +Visualization output data. The returned data type depends on the `plotter`. If matplotlib family is specified, this will be a `matplotlib.pyplot.Figure` data. + +### exclude + + + +`exclude(*filter_funcs, channels=None, instruction_types=None, check_subroutine=True)` + +Return a new `ScheduleBlock` with only the instructions from this `ScheduleBlock` *failing* at least one of the provided filters. This method is the complement of py:meth:\~self.filter, so that: + +```python +self.filter(args) + self.exclude(args) == self in terms of instructions included. +``` + + + Because `ScheduleBlock` is not aware of the execution time of the context instructions, excluding some instructions may change the execution time of the remaining instructions. + + +**Parameters** + +* **filter\_funcs** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*]*) – A list of Callables which take a `Instruction` and return a bool. +* **channels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – For example, `[DriveChannel(0), AcquireChannel(0)]`. +* **instruction\_types** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")*] |* [*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)") *| None*) – For example, `[PulseInstruction, AcquireInstruction]`. +* **check\_subroutine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to individually filter instructions inside of a subroutine defined by the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction. + +**Returns** + +`ScheduleBlock` consisting of instructions that do not match with at least one of filtering conditions. + +### filter + + + +`filter(*filter_funcs, channels=None, instruction_types=None, check_subroutine=True)` + +Return a new `ScheduleBlock` with only the instructions from this `ScheduleBlock` which pass though the provided filters; i.e. an instruction will be retained if every function in `filter_funcs` returns `True`, the instruction occurs on a channel type contained in `channels`, and the instruction type is contained in `instruction_types`. + + + Because `ScheduleBlock` is not aware of the execution time of the context instructions, filtering out some instructions may change the execution time of the remaining instructions. + + +If no arguments are provided, `self` is returned. + +**Parameters** + +* **filter\_funcs** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*]*) – A list of Callables which take a `Instruction` and return a bool. +* **channels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – For example, `[DriveChannel(0), AcquireChannel(0)]`. +* **instruction\_types** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")*] |* [*ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)") *| None*) – For example, `[PulseInstruction, AcquireInstruction]`. +* **check\_subroutine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to individually filter instructions inside a subroutine defined by the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction. + +**Returns** + +`ScheduleBlock` consisting of instructions that matches with filtering condition. + +### get\_parameters + + + +`get_parameters(parameter_name)` + +Get parameter object bound to this schedule by string name. + +Note that we can define different parameter objects with the same name, because these different objects are identified by their unique uuid. For example, + +```python +from qiskit import pulse, circuit + +amp1 = circuit.Parameter("amp") +amp2 = circuit.Parameter("amp") + +with pulse.build() as sub_prog: + pulse.play(pulse.Constant(100, amp1), pulse.DriveChannel(0)) + +with pulse.build() as main_prog: + pulse.call(sub_prog, name="sub") + pulse.play(pulse.Constant(100, amp2), pulse.DriveChannel(0)) + +main_prog.get_parameters("amp") +``` + +This returns a list of two parameters `amp1` and `amp2`. + +**Parameters** + +**parameter\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of parameter. + +**Returns** + +Parameter objects that have corresponding name. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")] + +### initialize\_from + + + +`classmethod initialize_from(other_program, name=None)` + +Create new schedule object with metadata of another schedule object. + +**Parameters** + +* **other\_program** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit program that provides metadata to new object. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of new schedule. Name of `block` is used by default. + +**Returns** + +New block object with name and metadata. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When `other_program` does not provide necessary information. + +**Return type** + +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_referenced + + + +`is_referenced()` + +Return True iff the current schedule block contains reference to subroutine. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_schedulable + + + +`is_schedulable()` + +Return `True` if all durations are assigned. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### replace + + + +`replace(old, new, inplace=True)` + +Return a `ScheduleBlock` with the `old` component replaced with a `new` component. + +**Parameters** + +* **old** ([*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule block component to replace. +* **new** ([*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Schedule block component to replace with. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Replace instruction by mutably modifying this `ScheduleBlock`. + +**Returns** + +The modified schedule block with `old` replaced by `new`. + +**Return type** + +[*ScheduleBlock*](#qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### scoped\_parameters + + + +`scoped_parameters()` + +Return unassigned parameters with scoped names. + + + Scoped parameters do not work correctly with Qiskit’s data model for parameter assignment. This implementation is consequently being removed in Qiskit 1.0. + + + + If a parameter is defined within a nested scope, it is prefixed with all parent-scope names with the delimiter string, which is “::”. If a reference key of the scope consists of multiple key strings, it will be represented by a single string joined with “,”. For example, “root::xgate,q0::amp” for the parameter “amp” defined in the reference specified by the key strings (“xgate”, “q0”). + + + + The method `qiskit.pulse.schedule.ScheduleBlock.scoped_parameters()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. There is no alternative to this method. Parameters must be mapped to references by checking the reference schedules directly. + + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")] + +### search\_parameters + + + +`search_parameters(parameter_regex)` + +Search parameter with regular expression. + + + Scoped parameters do not work correctly with Qiskit’s data model for parameter assignment. This implementation is consequently being removed in Qiskit 1.0. + + +This method looks for the scope-aware parameters. For example, + +```python +from qiskit import pulse, circuit + +amp1 = circuit.Parameter("amp") +amp2 = circuit.Parameter("amp") + +with pulse.build() as sub_prog: + pulse.play(pulse.Constant(100, amp1), pulse.DriveChannel(0)) + +with pulse.build() as main_prog: + pulse.call(sub_prog, name="sub") + pulse.play(pulse.Constant(100, amp2), pulse.DriveChannel(0)) + +main_prog.search_parameters("root::sub::amp") +``` + +This finds `amp1` with scoped name “root::sub::amp”. + + + The method `qiskit.pulse.schedule.ScheduleBlock.search_parameters()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. There is no alternative to this method. Parameters must be mapped to references by checking the reference schedules directly. + + +**Parameters** + +**parameter\_regex** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Regular expression for scoped parameter name. + +**Returns** + +Parameter objects that have corresponding name. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")] + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.AcquireChannel.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.AcquireChannel.md new file mode 100644 index 00000000000..7c91206e3ef --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.AcquireChannel.md @@ -0,0 +1,68 @@ +--- +title: AcquireChannel +description: API reference for qiskit.pulse.channels.AcquireChannel +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.AcquireChannel +--- + +# AcquireChannel + + + +`qiskit.pulse.channels.AcquireChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") + +Acquire channels are used to collect data. + +Channel class. + +**Parameters** + +**index** – Index of channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 'a'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.ControlChannel.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.ControlChannel.md new file mode 100644 index 00000000000..ea7d084e183 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.ControlChannel.md @@ -0,0 +1,68 @@ +--- +title: ControlChannel +description: API reference for qiskit.pulse.channels.ControlChannel +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.ControlChannel +--- + +# ControlChannel + + + +`qiskit.pulse.channels.ControlChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: `PulseChannel` + +Control channels provide supplementary control over the qubit to the drive channel. These are often associated with multi-qubit gate operations. They may not map trivially to a particular qubit index. + +Channel class. + +**Parameters** + +**index** – Index of channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 'u'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.DriveChannel.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.DriveChannel.md new file mode 100644 index 00000000000..3fc44b1ae8a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.DriveChannel.md @@ -0,0 +1,68 @@ +--- +title: DriveChannel +description: API reference for qiskit.pulse.channels.DriveChannel +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.DriveChannel +--- + +# DriveChannel + + + +`qiskit.pulse.channels.DriveChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: `PulseChannel` + +Drive channels transmit signals to qubits which enact gate operations. + +Channel class. + +**Parameters** + +**index** – Index of channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 'd'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.MeasureChannel.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.MeasureChannel.md new file mode 100644 index 00000000000..d8d8b51b3c4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.MeasureChannel.md @@ -0,0 +1,68 @@ +--- +title: MeasureChannel +description: API reference for qiskit.pulse.channels.MeasureChannel +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.MeasureChannel +--- + +# MeasureChannel + + + +`qiskit.pulse.channels.MeasureChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: `PulseChannel` + +Measure channels transmit measurement stimulus pulses for readout. + +Channel class. + +**Parameters** + +**index** – Index of channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 'm'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.MemorySlot.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.MemorySlot.md new file mode 100644 index 00000000000..e2806667cbd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.MemorySlot.md @@ -0,0 +1,68 @@ +--- +title: MemorySlot +description: API reference for qiskit.pulse.channels.MemorySlot +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.MemorySlot +--- + +# MemorySlot + + + +`qiskit.pulse.channels.MemorySlot(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: `ClassicalIOChannel` + +Memory slot channels represent classical memory storage. + +Channel class. + +**Parameters** + +**index** – Index of channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 'm'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.RegisterSlot.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.RegisterSlot.md new file mode 100644 index 00000000000..9ad0c1f3ea9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.RegisterSlot.md @@ -0,0 +1,68 @@ +--- +title: RegisterSlot +description: API reference for qiskit.pulse.channels.RegisterSlot +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.RegisterSlot +--- + +# RegisterSlot + + + +`qiskit.pulse.channels.RegisterSlot(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: `ClassicalIOChannel` + +Classical resister slot channels represent classical registers (low-latency classical memory). + +Channel class. + +**Parameters** + +**index** – Index of channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 'c'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.channels.SnapshotChannel.md b/docs/api/qiskit/0.46/qiskit.pulse.channels.SnapshotChannel.md new file mode 100644 index 00000000000..3f34458c12d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.channels.SnapshotChannel.md @@ -0,0 +1,64 @@ +--- +title: SnapshotChannel +description: API reference for qiskit.pulse.channels.SnapshotChannel +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.channels.SnapshotChannel +--- + +# SnapshotChannel + + + +`qiskit.pulse.channels.SnapshotChannel(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/channels.py "view source code") + +Bases: `ClassicalIOChannel` + +Snapshot channels are used to specify instructions for simulators. + +Create new snapshot channel. + +## Attributes + + + +### index + +Return the index of this channel. The index is a label for a control signal line typically mapped trivially to a qubit index. For instance, `DriveChannel(0)` labels the signal line driving the qubit labeled with index 0. + + + +### name + +Return the shorthand alias for this channel, which is based on its type and index. + + + +### parameters + +Parameters which determine the channel index. + + + +### prefix + +`str | None` + +`= 's'` + +A shorthand string prefix for characterizing the channel type. + +## Methods + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the channel is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.Acquire.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Acquire.md new file mode 100644 index 00000000000..ab5562f4621 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Acquire.md @@ -0,0 +1,289 @@ +--- +title: Acquire +description: API reference for qiskit.pulse.instructions.Acquire +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.Acquire +--- + +# Acquire + + + +`qiskit.pulse.instructions.Acquire(duration, channel, mem_slot=None, reg_slot=None, kernel=None, discriminator=None, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/acquire.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +The Acquire instruction is used to trigger the ADC associated with a particular qubit; e.g. instantiated with AcquireChannel(0), the Acquire command will trigger data collection for the channel associated with qubit 0 readout. This instruction also provides acquisition metadata: + +> * the number of cycles during which to acquire (in terms of dt), +> * the register slot to store classified, intermediary readout results, +> * the memory slot to return classified results, +> * the kernel to integrate raw data for each shot, and +> * the discriminator to classify kerneled IQ points. + +Create a new Acquire instruction. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Length of time to acquire data in terms of dt. +* **channel** ([*AcquireChannel*](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel")) – The channel that will acquire data. +* **mem\_slot** ([*MemorySlot*](qiskit.pulse.channels.MemorySlot "qiskit.pulse.channels.MemorySlot") *| None*) – The classical memory slot in which to store the classified readout result. +* **reg\_slot** ([*RegisterSlot*](qiskit.pulse.channels.RegisterSlot "qiskit.pulse.channels.RegisterSlot") *| None*) – The fast-access register slot in which to store the classified readout result for fast feedback. +* **kernel** (*Kernel | None*) – A `Kernel` for integrating raw data. +* **discriminator** (*Discriminator | None*) – A `Discriminator` for discriminating kerneled IQ data into 0/1 results. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction for display purposes. + +## Attributes + + + +### acquire + +Acquire channel to acquire data. The `AcquireChannel` index maps trivially to qubit index. + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### discriminator + +Return discrimination settings. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### kernel + +Return kernel settings. + + + +### mem\_slot + +The classical memory slot which will store the classified readout result. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### reg\_slot + +The fast-access register slot which will store the classified readout result for fast-feedback computation. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.Call.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Call.md new file mode 100644 index 00000000000..e0147d1868f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Call.md @@ -0,0 +1,303 @@ +--- +title: Call +description: API reference for qiskit.pulse.instructions.Call +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.Call +--- + +# Call + + + +`qiskit.pulse.instructions.Call(subroutine, value_dict=None, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/call.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +Pulse `Call` instruction. + +The `Call` instruction represents the calling of a referenced subroutine (schedule). It enables code reuse both within the pulse representation and hardware (if supported). + +Define new subroutine. + + + Inline subroutine is mutable. This requires special care for modification. + + + + The class `qiskit.pulse.instructions.call.Call` is deprecated as of qiskit-terra 0.25.0. It will be removed in the Qiskit 1.0 release. Instead, use the pulse builder function qiskit.pulse.builder.call(subroutine) within an active building context. + + +**Parameters** + +* **subroutine** (*Union\[*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule")*,* [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")*]*) – A program subroutine to be referred to. +* **value\_dict** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – Mapping of parameter object to assigned value. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Unique ID of this subroutine. If not provided, this is generated based on the subroutine name. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If subroutine is not valid data format. + +## Attributes + + + +### arguments + +Parameters dictionary to be assigned to subroutine. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Unassigned parameters which determine the instruction behavior. + + + +### prefix + +`= 'call'` + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + + + +### subroutine + +Return attached subroutine. + +**Returns** + +The program referenced by the call. + +**Return type** + +program (Union\[[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule"), [ScheduleBlock](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")]) + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### assigned\_subroutine + + + +`assigned_subroutine()` + +Returns this subroutine with the parameters assigned. + + + This function may be often called internally for class equality check despite its overhead of parameter assignment. The subroutine with parameter assigned is cached based on `.argument` hash. Once this argument is updated, new assigned instance will be returned. Note that this update is not mutable operation. + + +**Returns** + +Attached program. + +**Return type** + +program (Union\[[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule"), [ScheduleBlock](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")]) + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.Delay.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Delay.md new file mode 100644 index 00000000000..3b634347219 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Delay.md @@ -0,0 +1,263 @@ +--- +title: Delay +description: API reference for qiskit.pulse.instructions.Delay +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.Delay +--- + +# Delay + + + +`qiskit.pulse.instructions.Delay(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/delay.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +A blocking instruction with no other effect. The delay is used for aligning and scheduling other instructions. + +**Example** + +To schedule an instruction at time = 10, on a channel assigned to the variable `channel`, the following could be used: + +```python +sched = Schedule(name="Delay instruction example") +sched += Delay(10, channel) +sched += Gaussian(duration, amp, sigma, channel) +``` + +The `channel` will output no signal from time=0 up until time=10. + +Create a new delay instruction. + +No other instruction may be scheduled within a `Delay`. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Length of time of the delay in terms of dt. +* **channel** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – The channel that will have the delay. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the delay for display purposes. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.Play.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Play.md new file mode 100644 index 00000000000..125e5646447 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Play.md @@ -0,0 +1,257 @@ +--- +title: Play +description: API reference for qiskit.pulse.instructions.Play +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.Play +--- + +# Play + + + +`qiskit.pulse.instructions.Play(pulse, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/play.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +This instruction is responsible for applying a pulse on a channel. + +The pulse specifies the exact time dynamics of the output signal envelope for a limited time. The output is modulated by a phase and frequency which are controlled by separate instructions. The pulse duration must be fixed, and is implicitly given in terms of the cycle time, dt, of the backend. + +Create a new pulse instruction. + +**Parameters** + +* **pulse** (*Pulse*) – A pulse waveform description, such as [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform"). +* **channel** (*PulseChannel*) – The channel to which the pulse is applied. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the instruction for display purposes. Defaults to `pulse.name`. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### pulse + +A description of the samples that will be played. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.Reference.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Reference.md new file mode 100644 index 00000000000..495498f1775 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Reference.md @@ -0,0 +1,268 @@ +--- +title: Reference +description: API reference for qiskit.pulse.instructions.Reference +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.Reference +--- + +# Reference + + + +`qiskit.pulse.instructions.Reference(name, *extra_keys)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/reference.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +Pulse compiler directive that refers to a subroutine. + +If a pulse program uses the same subset of instructions multiple times, then using the [`Reference`](#qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference") class may significantly reduce the memory footprint of the program. This instruction only stores the set of strings to identify the subroutine. + +The actual pulse program can be stored in the `ScheduleBlock.references` of the [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") that this reference instruction belongs to. + +You can later assign schedules with the `ScheduleBlock.assign_references()` method. This allows you to build the main program without knowing the actual subroutine, that is supplied at a later time. + +Create new reference. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of subroutine. +* **extra\_keys** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional. A set of string keys that may be necessary to refer to a particular subroutine. For example, when we use “sx” as a name to refer to the subroutine of an sx pulse, this name might be used among schedules for different qubits. In this example, you may specify “q0” in the extra keys to distinguish the sx schedule for qubit 0 from others. The user can use an arbitrary number of extra string keys to uniquely determine the subroutine. + +## Attributes + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### key\_delimiter + +`= ','` + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### ref\_keys + +Returns unique key of the subroutine. + + + +### scope\_delimiter = ' + +`= ':` + +`= '::'` + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.RelativeBarrier.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.RelativeBarrier.md new file mode 100644 index 00000000000..23ef2e0c82b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.RelativeBarrier.md @@ -0,0 +1,244 @@ +--- +title: RelativeBarrier +description: API reference for qiskit.pulse.instructions.RelativeBarrier +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.RelativeBarrier +--- + +# RelativeBarrier + + + +`qiskit.pulse.instructions.RelativeBarrier(*channels, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/directives.py "view source code") + +Bases: `Directive` + +Pulse `RelativeBarrier` directive. + +Create a relative barrier directive. + +The barrier directive blocks instructions within the same schedule as the barrier on channels contained within this barrier from moving through the barrier in time. + +**Parameters** + +* **channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – The channel that the barrier applies to. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the directive for display purposes. + +## Attributes + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.SetFrequency.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.SetFrequency.md new file mode 100644 index 00000000000..771d723084f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.SetFrequency.md @@ -0,0 +1,265 @@ +--- +title: SetFrequency +description: API reference for qiskit.pulse.instructions.SetFrequency +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.SetFrequency +--- + +# SetFrequency + + + +`qiskit.pulse.instructions.SetFrequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/frequency.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +Set the channel frequency. This instruction operates on `PulseChannel` s. A `PulseChannel` creates pulses of the form + +$$ +Re[\exp(i 2\pi f jdt + \phi) d_j]. + + +$$ + +Here, $f$ is the frequency of the channel. The instruction `SetFrequency` allows the user to set the value of $f$. All pulses that are played on a channel after SetFrequency has been called will have the corresponding frequency. + +The duration of SetFrequency is 0. + +Creates a new set channel frequency instruction. + +**Parameters** + +* **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – New frequency of the channel in Hz. +* **channel** (*PulseChannel*) – The channel this instruction operates on. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of this set channel frequency instruction. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### frequency + +New frequency. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.SetPhase.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.SetPhase.md new file mode 100644 index 00000000000..20ee6dfade3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.SetPhase.md @@ -0,0 +1,263 @@ +--- +title: SetPhase +description: API reference for qiskit.pulse.instructions.SetPhase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.SetPhase +--- + +# SetPhase + + + +`qiskit.pulse.instructions.SetPhase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/phase.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +The set phase instruction sets the phase of the proceeding pulses on that channel to `phase` radians. + +In particular, a PulseChannel creates pulses of the form + +$$ +Re[\exp(i 2\pi f jdt + \phi) d_j] +$$ + +The `SetPhase` instruction sets $\phi$ to the instruction’s `phase` operand. + +Instantiate a set phase instruction, setting the output signal phase on `channel` to `phase` \[radians]. + +**Parameters** + +* **phase** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The rotation angle in radians. +* **channel** (*PulseChannel*) – The channel this instruction operates on. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this instruction. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### phase + +Return the rotation angle enacted by this instruction in radians. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftFrequency.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftFrequency.md new file mode 100644 index 00000000000..9e0ca23a4fb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftFrequency.md @@ -0,0 +1,255 @@ +--- +title: ShiftFrequency +description: API reference for qiskit.pulse.instructions.ShiftFrequency +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.ShiftFrequency +--- + +# ShiftFrequency + + + +`qiskit.pulse.instructions.ShiftFrequency(frequency, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/frequency.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +Shift the channel frequency away from the current frequency. + +Creates a new shift frequency instruction. + +**Parameters** + +* **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Frequency shift of the channel in Hz. +* **channel** (*PulseChannel*) – The channel this instruction operates on. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of this set channel frequency instruction. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### frequency + +Frequency shift from the set frequency. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftPhase.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftPhase.md new file mode 100644 index 00000000000..e6da3a67285 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.ShiftPhase.md @@ -0,0 +1,267 @@ +--- +title: ShiftPhase +description: API reference for qiskit.pulse.instructions.ShiftPhase +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.ShiftPhase +--- + +# ShiftPhase + + + +`qiskit.pulse.instructions.ShiftPhase(phase, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/phase.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +The shift phase instruction updates the modulation phase of proceeding pulses played on the same [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel"). It is a relative increase in phase determined by the `phase` operand. + +In particular, a PulseChannel creates pulses of the form + +$$ +Re[\exp(i 2\pi f jdt + \phi) d_j]. + + +$$ + +The `ShiftPhase` instruction causes $\phi$ to be increased by the instruction’s `phase` operand. This will affect all pulses following on the same channel. + +The qubit phase is tracked in software, enabling instantaneous, nearly error-free Z-rotations by using a ShiftPhase to update the frame tracking the qubit state. + +Instantiate a shift phase instruction, increasing the output signal phase on `channel` by `phase` \[radians]. + +**Parameters** + +* **phase** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The rotation angle in radians. +* **channel** (*PulseChannel*) – The channel this instruction operates on. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this instruction. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### phase + +Return the rotation angle enacted by this instruction in radians. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.Snapshot.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Snapshot.md new file mode 100644 index 00000000000..5ba7515d7e3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.Snapshot.md @@ -0,0 +1,261 @@ +--- +title: Snapshot +description: API reference for qiskit.pulse.instructions.Snapshot +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.Snapshot +--- + +# Snapshot + + + +`qiskit.pulse.instructions.Snapshot(label, snapshot_type='statevector', name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/snapshot.py "view source code") + +Bases: [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction") + +An instruction targeted for simulators, to capture a moment in the simulation. + +Create new snapshot. + +**Parameters** + +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Snapshot label which is used to identify the snapshot in the output. +* **snapshot\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Type of snapshot, e.g., “state” (take a snapshot of the quantum state). The types of snapshots offered are defined by the simulator used. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Snapshot name which defaults to `label`. This parameter is only for display purposes and is not taken into account during comparison. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on; trivially, a `SnapshotChannel`. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### label + +Label of snapshot. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + + + +### type + +Type of snapshot. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.instructions.TimeBlockade.md b/docs/api/qiskit/0.46/qiskit.pulse.instructions.TimeBlockade.md new file mode 100644 index 00000000000..f98c6b69bc4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.instructions.TimeBlockade.md @@ -0,0 +1,280 @@ +--- +title: TimeBlockade +description: API reference for qiskit.pulse.instructions.TimeBlockade +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.instructions.TimeBlockade +--- + +# TimeBlockade + + + +`qiskit.pulse.instructions.TimeBlockade(duration, channel, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/instructions/directives.py "view source code") + +Bases: `Directive` + +Pulse `TimeBlockade` directive. + +This instruction is intended to be used internally within the pulse builder, to convert [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") into [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"). Because [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") cannot take an absolute instruction time interval, this directive helps the block representation to find the starting time of an instruction. + +**Example** + +This schedule plays constant pulse at t0 = 120. + +```python +schedule = Schedule() +schedule.insert(120, Play(Constant(10, 0.1), DriveChannel(0))) +``` + +This schedule block is expected to be identical to above at a time of execution. + +```python +block = ScheduleBlock() +block.append(TimeBlockade(120, DriveChannel(0))) +block.append(Play(Constant(10, 0.1), DriveChannel(0))) +``` + +Such conversion may be done by + +```python +from qiskit.pulse.transforms import block_to_schedule, remove_directives + +schedule = remove_directives(block_to_schedule(block)) +``` + + + The TimeBlockade instruction behaves almost identically to [`Delay`](qiskit.pulse.instructions.Delay "qiskit.pulse.instructions.Delay") instruction. However, the TimeBlockade is just a compiler directive and must be removed before execution. This may be done by [`remove_directives()`](pulse#qiskit.pulse.transforms.remove_directives "qiskit.pulse.transforms.remove_directives") transform. Once these directives are removed, occupied timeslots are released and user can insert another instruction without timing overlap. + + +Create a time blockade directive. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Length of time of the occupation in terms of dt. +* **channel** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – The channel that will be the occupied. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the time blockade for display purposes. + +## Attributes + + + +### channel + +Return the [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") that this instruction is scheduled on. + + + +### channels + +Returns the channels that this schedule uses. + + + +### duration + +Duration of this instruction. + + + +### id + +Unique identifier for this instruction. + + + +### instructions + +Iterable for getting instructions from Schedule tree. + + + +### name + +Name of this instruction. + + + +### operands + +Return instruction operands. + + + +### parameters + +Parameters which determine the instruction behavior. + + + +### start\_time + +Relative begin time of this instruction. + + + +### stop\_time + +Relative end time of this instruction. + +## Methods + +### append + + + +`append(schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`. + +**Parameters** + +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to be appended +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` a this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### ch\_duration + + + +`ch_duration(*channels)` + +Return duration of the supplied channels in this Instruction. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_start\_time + + + +`ch_start_time(*channels)` + +Return minimum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### ch\_stop\_time + + + +`ch_stop_time(*channels)` + +Return maximum start time for supplied channels. + +**Parameters** + +**\*channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*]*) – Supplied channels + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### draw + + + +`draw(dt=1, style=None, filename=None, interp_method=None, scale=1, plot_all=False, plot_range=None, interactive=False, table=True, label=False, framechange=True, channels=None)` + +Plot the instruction. + + + The method `qiskit.pulse.instructions.instruction.Instruction.draw()` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. No direct alternative is being provided to drawing individual pulses. But, instructions can be visualized as part of a complete schedule using `qiskit.visualization.pulse_drawer`. + + +**Parameters** + +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Time interval of samples +* **style** (*Optional\[SchedStyle]*) – A style sheet to configure plot appearance +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name required to save pulse image +* **interp\_method** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – A function for interpolation +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative visual scaling of waveform amplitudes +* **plot\_all** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot empty channels +* **plot\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – A tuple of time range to plot +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set true show the circuit in a new window (this depends on the matplotlib backend being used supporting this) +* **table** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Draw event table for supported instructions +* **label** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label individual instructions +* **framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Add framechange indicators +* **channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A list of channel names to plot + +**Returns** + +A matplotlib figure object of the pulse schedule + +**Return type** + +matplotlib.figure + +### insert + + + +`insert(start_time, schedule, name=None)` + +Return a new [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") with `schedule` inserted within `self` at `start_time`. + +**Parameters** + +* **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule schedule +* **schedule** (*Union\['Schedule', 'Instruction']*) – Schedule or instruction to insert +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +A new schedule with `schedule` inserted with this instruction at t=0. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### shift + + + +`shift(time, name=None)` + +Return a new schedule shifted forward by time. + +**Parameters** + +* **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to name of self + +**Returns** + +The shifted schedule. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Constant_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Constant_class.rst.md new file mode 100644 index 00000000000..c6ca45c4016 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Constant_class.rst.md @@ -0,0 +1,45 @@ +--- +title: Constant +description: API reference for qiskit.pulse.library.Constant +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.Constant +--- + +# Constant + + + +`qiskit.pulse.library.Constant(duration, amp, angle=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A simple constant pulse, with an amplitude value and a duration: + +$$ +f(x) = \text{amp}\times\exp\left(i\text{angle}\right) , 0 <= x < duration +f(x) = 0 , elsewhere +$$ + +Create new pulse instance. + +**Parameters** + +* **duration** – Pulse length in terms of the sampling period dt. +* **amp** – The magnitude of the amplitude of the square envelope. Complex amp support is deprecated. +* **angle** – The angle of the complex amplitude of the square envelope. Default value 0. +* **name** – Display name for this pulse envelope. +* **limit\_amplitude** – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +## Attributes + + + +### alias + +`= 'Constant'` + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Cos_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Cos_class.rst.md new file mode 100644 index 00000000000..9dcb8eb5e53 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Cos_class.rst.md @@ -0,0 +1,44 @@ +--- +title: Cos +description: API reference for qiskit.pulse.library.Cos +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.Cos +--- + + + +# qiskit.pulse.library.Cos + + + +`qiskit.pulse.library.Cos(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +A cosine pulse. + +The envelope of the pulse is given by: + +$$ +f(x) = \text{A}\cos\left(2\pi\text{freq}x+\text{phase}\right) , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the cosine wave. Wave range is \[-amp,\`amp\`]. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The phase of the cosine wave (note that this is not equivalent to the angle of the complex amplitude). +* **freq** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The frequency of the cosine wave, in terms of 1 over sampling period. If not provided defaults to a single cycle (i.e :math:’frac\{1}\{text\{duration}}’). The frequency is limited to the range $\left(0,0.5\right]$ (the Nyquist frequency). +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Drag_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Drag_class.rst.md new file mode 100644 index 00000000000..7e576b79092 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Drag_class.rst.md @@ -0,0 +1,61 @@ +--- +title: Drag +description: API reference for qiskit.pulse.library.Drag +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.Drag +--- + +# Drag + + + +`qiskit.pulse.library.Drag(duration, amp, sigma, beta, angle=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +The Derivative Removal by Adiabatic Gate (DRAG) pulse is a standard Gaussian pulse with an additional Gaussian derivative component and lifting applied. + +It can be calibrated either to reduce the phase error due to virtual population of the $|2\rangle$ state during the pulse or to reduce the frequency spectrum of a standard Gaussian pulse near the $|1\rangle\leftrightarrow|2\rangle$ transition, reducing the chance of leakage to the $|2\rangle$ state. + +$$ +\begin{aligned} +g(x) &= \exp\Bigl(-\frac12 \frac{(x - \text{duration}/2)^2}{\text{sigma}^2}\Bigr)\\ +g'(x) &= \text{A}\times\frac{g(x)-g(-1)}{1-g(-1)}\\ +f(x) &= g'(x) \times \Bigl(1 + 1j \times \text{beta} \times \Bigl(-\frac{x - \text{duration}/2}{\text{sigma}^2}\Bigr) \Bigr), + \quad 0 \le x < \text{duration} +\end{aligned} +$$ + +where $g(x)$ is a standard unlifted Gaussian waveform, $g'(x)$ is the lifted [`Gaussian`](qiskit.pulse.library.Gaussian_class.rst#qiskit.pulse.library.Gaussian "qiskit.pulse.library.Gaussian") waveform, and $\text{A} = \text{amp} \times \exp\left(i\times\text{angle}\right)$. + +**References** + +1. [*Gambetta, J. M., Motzoi, F., Merkel, S. T. & Wilhelm, F. K. Analytic control methods for high-fidelity unitary operations in a weakly nonlinear oscillator. Phys. Rev. A 83, 012308 (2011).*](https://link.aps.org/doi/10.1103/PhysRevA.83.012308) + +2. [*F. Motzoi, J. M. Gambetta, P. Rebentrost, and F. K. Wilhelm Phys. Rev. Lett. 103, 110501 – Published 8 September 2009.*](https://link.aps.org/doi/10.1103/PhysRevLett.103.110501) + +Create new pulse instance. + +**Parameters** + +* **duration** – Pulse length in terms of the sampling period dt. +* **amp** – The magnitude of the amplitude of the DRAG envelope. Complex amp support is deprecated. +* **sigma** – A measure of how wide or narrow the Gaussian peak is; described mathematically in the class docstring. +* **beta** – The correction amplitude. +* **angle** – The angle of the complex amplitude of the DRAG envelope. Default value 0. +* **name** – Display name for this pulse envelope. +* **limit\_amplitude** – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +## Attributes + + + +### alias + +`= 'Drag'` + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianDeriv.md b/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianDeriv.md new file mode 100644 index 00000000000..445dabbda96 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianDeriv.md @@ -0,0 +1,44 @@ +--- +title: GaussianDeriv +description: API reference for qiskit.pulse.library.GaussianDeriv +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.GaussianDeriv +--- + + + +# qiskit.pulse.library.GaussianDeriv + + + +`qiskit.pulse.library.GaussianDeriv(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +An unnormalized Gaussian derivative pulse. + +The Gaussian function is centered around the halfway point of the pulse, and the envelope of the pulse is given by: + +$$ +f(x) = -\text{A}\frac{x-\mu}{\text{sigma}^{2}}\exp + \left[-\left(\frac{x-\mu}{2\text{sigma}}\right)^{2}\right] , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$, and $\mu=\text{duration}/2$. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the pulse (the value of the corresponding Gaussian at the midpoint duration/2). +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A measure of how wide or narrow the corresponding Gaussian peak is in terms of dt; described mathematically in the class docstring. +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquare.md b/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquare.md new file mode 100644 index 00000000000..2f56de68217 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquare.md @@ -0,0 +1,79 @@ +--- +title: GaussianSquare +description: API reference for qiskit.pulse.library.GaussianSquare +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.GaussianSquare +--- + +# GaussianSquare + + + +`qiskit.pulse.library.GaussianSquare(duration, amp, sigma, width=None, angle=None, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A square pulse with a Gaussian shaped risefall on both sides lifted such that its first sample is zero. + +Exactly one of the `risefall_sigma_ratio` and `width` parameters has to be specified. + +If `risefall_sigma_ratio` is not None and `width` is None: + +$$ +\begin{aligned} +\text{risefall} &= \text{risefall\_sigma\_ratio} \times \text{sigma}\\ +\text{width} &= \text{duration} - 2 \times \text{risefall} +\end{aligned} +$$ + +If `width` is not None and `risefall_sigma_ratio` is None: + +$$ +\text{risefall} = \frac{\text{duration} - \text{width}}{2} + + +$$ + +In both cases, the lifted gaussian square pulse $f'(x)$ is defined as: + +$$ +\begin{aligned} +f'(x) &= \begin{cases} \exp\biggl(-\frac12 \frac{(x - \text{risefall})^2}{\text{sigma}^2}\biggr) & x < \text{risefall}\\ + 1 & \text{risefall} \le x < \text{risefall} + \text{width}\\ + \exp\biggl(-\frac12 \frac{{\bigl(x - (\text{risefall} + \text{width})\bigr)}^2} {\text{sigma}^2} \biggr) & \text{risefall} + \text{width} \le x \end{cases}\\ +f(x) &= \text{A} \times \frac{f'(x) - f'(-1)}{1-f'(-1)}, \quad 0 \le x < \text{duration} +\end{aligned} +$$ + +where $f'(x)$ is the gaussian square waveform without lifting or amplitude scaling, and $\text{A} = \text{amp} \times \exp\left(i\times\text{angle}\right)$. + +Create new pulse instance. + +**Parameters** + +* **duration** – Pulse length in terms of the sampling period dt. +* **amp** – The magnitude of the amplitude of the Gaussian and square pulse. Complex amp support is deprecated. +* **sigma** – A measure of how wide or narrow the Gaussian risefall is; see the class docstring for more details. +* **width** – The duration of the embedded square pulse. +* **angle** – The angle of the complex amplitude of the pulse. Default value 0. +* **risefall\_sigma\_ratio** – The ratio of each risefall duration to sigma. +* **name** – Display name for this pulse envelope. +* **limit\_amplitude** – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When width and risefall\_sigma\_ratio are both empty or both non-empty. + +## Attributes + + + +### alias + +`= 'GaussianSquare'` + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquareDrag.md b/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquareDrag.md new file mode 100644 index 00000000000..54c55a57c26 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.GaussianSquareDrag.md @@ -0,0 +1,90 @@ +--- +title: GaussianSquareDrag +description: API reference for qiskit.pulse.library.GaussianSquareDrag +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.GaussianSquareDrag +--- + + + +# qiskit.pulse.library.GaussianSquareDrag + + + +`qiskit.pulse.library.GaussianSquareDrag(duration, amp, sigma, beta, width=None, angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +A square pulse with a Drag shaped rise and fall + +This pulse shape is similar to [`GaussianSquare`](qiskit.pulse.library.GaussianSquare "qiskit.pulse.library.GaussianSquare") but uses [`Drag`](qiskit.pulse.library.Drag_class.rst#qiskit.pulse.library.Drag "qiskit.pulse.library.Drag") for its rise and fall instead of [`Gaussian`](qiskit.pulse.library.Gaussian_class.rst#qiskit.pulse.library.Gaussian "qiskit.pulse.library.Gaussian"). The addition of the DRAG component of the rise and fall is sometimes helpful in suppressing the spectral content of the pulse at frequencies near to, but slightly offset from, the fundamental frequency of the drive. When there is a spectator qubit close in frequency to the fundamental frequency, suppressing the drive at the spectator’s frequency can help avoid unwanted excitation of the spectator. + +Exactly one of the `risefall_sigma_ratio` and `width` parameters has to be specified. + +If `risefall_sigma_ratio` is not `None` and `width` is `None`: + +$$ +\begin{aligned} +\text{risefall} &= \text{risefall\_sigma\_ratio} \times \text{sigma}\\ +\text{width} &= \text{duration} - 2 \times \text{risefall} +\end{aligned} +$$ + +If `width` is not None and `risefall_sigma_ratio` is None: + +$$ +\text{risefall} = \frac{\text{duration} - \text{width}}{2} + + +$$ + +Gaussian $g(x, c, σ)$ and lifted gaussian $g'(x, c, σ)$ curves can be written as: + +$$ +\begin{aligned} +g(x, c, σ) &= \exp\Bigl(-\frac12 \frac{(x - c)^2}{σ^2}\Bigr)\\ +g'(x, c, σ) &= \frac{g(x, c, σ)-g(-1, c, σ)}{1-g(-1, c, σ)} +\end{aligned} +$$ + +From these, the lifted DRAG curve $d'(x, c, σ, β)$ can be written as + +$$ +d'(x, c, σ, β) = g'(x, c, σ) \times \Bigl(1 + 1j \times β \times \Bigl(-\frac{x - c}{σ^2}\Bigr)\Bigr) +$$ + +The lifted gaussian square drag pulse $f'(x)$ is defined as: + +$$ +\begin{aligned} +f'(x) &= \begin{cases} \text{A} \times d'(x, \text{risefall}, \text{sigma}, \text{beta}) & x < \text{risefall}\\ + \text{A} & \text{risefall} \le x < \text{risefall} + \text{width}\\ + \text{A} \times \times d'( x - (\text{risefall} + \text{width}), \text{risefall}, \text{sigma}, \text{beta} ) & \text{risefall} + \text{width} \le x \end{cases}\\ +\end{aligned} +$$ + +where $\text{A} = \text{amp} \times \exp\left(i\times\text{angle}\right)$. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The amplitude of the DRAG rise and fall and of the square pulse. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A measure of how wide or narrow the DRAG risefall is; see the class docstring for more details. +* **beta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The DRAG correction amplitude. +* **width** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The duration of the embedded square pulse. +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **risefall\_sigma\_ratio** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The ratio of each risefall duration to sigma. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When width and risefall\_sigma\_ratio are both empty or both non-empty. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Gaussian_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Gaussian_class.rst.md new file mode 100644 index 00000000000..1af4a6bbbec --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Gaussian_class.rst.md @@ -0,0 +1,50 @@ +--- +title: Gaussian +description: API reference for qiskit.pulse.library.Gaussian +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.Gaussian +--- + +# Gaussian + + + +`qiskit.pulse.library.Gaussian(duration, amp, sigma, angle=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A lifted and truncated pulse envelope shaped according to the Gaussian function whose mean is centered at the center of the pulse (duration / 2): + +$$ +\begin{aligned} +f'(x) &= \exp\Bigl( -\frac12 \frac{{(x - \text{duration}/2)}^2}{\text{sigma}^2} \Bigr)\\ +f(x) &= \text{A} \times \frac{f'(x) - f'(-1)}{1-f'(-1)}, \quad 0 \le x < \text{duration} +\end{aligned} +$$ + +where $f'(x)$ is the gaussian waveform without lifting or amplitude scaling, and $\text{A} = \text{amp} \times \exp\left(i\times\text{angle}\right)$. + +Create new pulse instance. + +**Parameters** + +* **duration** – Pulse length in terms of the sampling period dt. +* **amp** – The magnitude of the amplitude of the Gaussian envelope. Complex amp support is deprecated. +* **sigma** – A measure of how wide or narrow the Gaussian peak is; described mathematically in the class docstring. +* **angle** – The angle of the complex amplitude of the Gaussian envelope. Default value 0. +* **name** – Display name for this pulse envelope. +* **limit\_amplitude** – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +## Attributes + + + +### alias + +`= 'Gaussian'` + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.ParametricPulse.md b/docs/api/qiskit/0.46/qiskit.pulse.library.ParametricPulse.md new file mode 100644 index 00000000000..37043893531 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.ParametricPulse.md @@ -0,0 +1,138 @@ +--- +title: ParametricPulse +description: API reference for qiskit.pulse.library.ParametricPulse +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.ParametricPulse +--- + +# ParametricPulse + + + +`qiskit.pulse.library.ParametricPulse(duration, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/parametric_pulses.py "view source code") + +Bases: `Pulse` + +The abstract superclass for parametric pulses. + + + This class was superseded by [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") and is deprecated. It will be removed in Qiskit 1.0 because of the poor flexibility for defining a new waveform type and serializing it through the [`qiskit.qpy`](qpy#module-qiskit.qpy "qiskit.qpy") framework. + + +Create a parametric pulse and validate the input parameters. + + + The class `qiskit.pulse.library.parametric_pulses.ParametricPulse` is deprecated as of qiskit-terra 0.46. It will be removed in Qiskit 1.0. Instead, use SymbolicPulse because of QPY serialization support. See qiskit.pulse.library.symbolic\_pulses for details. + + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +## Attributes + + + +### duration + + + +### name + + + +### id + +Unique identifier for this pulse. + + + +### limit\_amplitude + +`= True` + + + +### parameters + +Return a dictionary containing the pulse’s parameters. + +## Methods + +### draw + + + +`draw(style=None, backend=None, time_range=None, time_unit='dt', show_waveform_info=True, plotter='mpl2d', axis=None)` + +Plot the interpolated envelope of pulse. + +**Parameters** + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. + +* **backend** (*Optional\[BaseBackend]*) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple `(tmin, tmax)`. + +* **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either `dt` or `ns`. The unit of `ns` is available only when `backend` object is provided. + +* **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show waveform annotations, i.e. name, of waveforms. Set `True` to show additional information about waveforms. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl2d: Matplotlib API for 2D image generation. + Matplotlib API to generate 2D image. Charts are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as `axis` input. + ``` + + axis and style kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given `axis` instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details. + +**Returns** + +Visualization output data. The returned data type depends on the `plotter`. If matplotlib family is specified, this will be a `matplotlib.pyplot.Figure` data. + +### get\_waveform + + + +`abstract get_waveform()` + +Return a Waveform with samples filled according to the formula that the pulse represents and the parameter values it contains. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### validate\_parameters + + + +`abstract validate_parameters()` + +Validate parameters. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the parameters passed are not valid. + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Sawtooth_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Sawtooth_class.rst.md new file mode 100644 index 00000000000..f3c3f650ea7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Sawtooth_class.rst.md @@ -0,0 +1,45 @@ +--- +title: Sawtooth +description: API reference for qiskit.pulse.library.Sawtooth +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.Sawtooth +--- + + + +# qiskit.pulse.library.Sawtooth + + + +`qiskit.pulse.library.Sawtooth(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +A sawtooth pulse. + +The envelope of the pulse is given by: + +$$ +f(x) = 2\text{A}\left[g\left(x\right)- + \lfloor g\left(x\right)+\frac{1}{2}\rfloor\right] +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$, $g\left(x\right)=x\times\text{freq}+\frac{\text{phase}}{2\pi}$, and $\lfloor ...\rfloor$ is the floor operation. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the sawtooth wave. Wave range is \[-amp,\`amp\`]. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The phase of the sawtooth wave (note that this is not equivalent to the angle of the complex amplitude) +* **freq** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The frequency of the sawtooth wave, in terms of 1 over sampling period. If not provided defaults to a single cycle (i.e :math:’frac\{1}\{text\{duration}}’). The frequency is limited to the range $\left(0,0.5\right]$ (the Nyquist frequency). +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.SechDeriv.md b/docs/api/qiskit/0.46/qiskit.pulse.library.SechDeriv.md new file mode 100644 index 00000000000..7a8151f033f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.SechDeriv.md @@ -0,0 +1,44 @@ +--- +title: SechDeriv +description: API reference for qiskit.pulse.library.SechDeriv +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.SechDeriv +--- + + + +# qiskit.pulse.library.SechDeriv + + + +`qiskit.pulse.library.SechDeriv(duration, amp, sigma, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +An unnormalized sech derivative pulse. + +The sech function is centered around the halfway point of the pulse, and the envelope of the pulse is given by: + +$$ +f(x) = \text{A}\frac{d}{dx}\left[\text{sech} + \left(\frac{x-\mu}{\text{sigma}}\right)\right] , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$, $\mu=\text{duration}/2$, and $d/dx$ is a derivative with respect to x. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the pulse (the value of the corresponding sech function at the midpoint duration/2). +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A measure of how wide or narrow the corresponding sech peak is, in terms of dt; described mathematically in the class docstring. +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Sech_fun.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Sech_fun.rst.md new file mode 100644 index 00000000000..7ad40da19a5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Sech_fun.rst.md @@ -0,0 +1,53 @@ +--- +title: Sech +description: API reference for qiskit.pulse.library.Sech +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.Sech +--- + + + +# qiskit.pulse.library.Sech + + + +`qiskit.pulse.library.Sech(duration, amp, sigma, angle=0.0, name=None, zero_ends=True, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +An unnormalized sech pulse. + +The sech function is centered around the halfway point of the pulse, and the envelope of the pulse is given by: + +$$ +f(x) = \text{A}\text{sech}\left( + \frac{x-\mu}{\text{sigma}}\right) , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$, and $\mu=\text{duration}/2$. + +If zero\_ends is set to True, the output y is modified: .. math: + +```python +y\left(x\right) \mapsto \text{A}\frac{y-y^{*}}{\text{A}-y^{*}}, +``` + +where $y^{*}$ is the value of $y$ at the endpoints (at $x=-1 and :math:`x=\text{duration}+1$). This shifts the endpoints value to zero, while also rescaling to preserve the amplitude at :math:text\{duration}/2\`\`. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the pulse (the value at the midpoint duration/2). +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A measure of how wide or narrow the sech peak is in terms of dt; described mathematically in the class docstring. +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **zero\_ends** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If True, zeros the ends at x = -1, x = duration + 1, but rescales to preserve amp. Default value True. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Sin_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Sin_class.rst.md new file mode 100644 index 00000000000..770520300bf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Sin_class.rst.md @@ -0,0 +1,44 @@ +--- +title: Sin +description: API reference for qiskit.pulse.library.Sin +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.Sin +--- + + + +# qiskit.pulse.library.Sin + + + +`qiskit.pulse.library.Sin(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +A sinusoidal pulse. + +The envelope of the pulse is given by: + +$$ +f(x) = \text{A}\sin\left(2\pi\text{freq}x+\text{phase}\right) , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the sinusoidal wave. Wave range is \[-amp,\`amp\`]. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The phase of the sinusoidal wave (note that this is not equivalent to the angle of the complex amplitude) +* **freq** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The frequency of the sinusoidal wave, in terms of 1 over sampling period. If not provided defaults to a single cycle (i.e :math:’frac\{1}\{text\{duration}}’). The frequency is limited to the range $\left(0,0.5\right]$ (the Nyquist frequency). +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Square_fun.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Square_fun.rst.md new file mode 100644 index 00000000000..3910c9f65d4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Square_fun.rst.md @@ -0,0 +1,45 @@ +--- +title: Square +description: API reference for qiskit.pulse.library.Square +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.Square +--- + + + +# qiskit.pulse.library.Square + + + +`qiskit.pulse.library.Square(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +A square wave pulse. + +The envelope of the pulse is given by: + +$$ +f(x) = \text{A}\text{sign}\left[\sin + \left(2\pi x\times\text{freq}+\text{phase}\right)\right] , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$, and $\text{sign}$ is the sign function with the convention $\text{sign}\left(0\right)=1$. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the square wave. Wave range is \[-amp,\`amp\`]. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The phase of the square wave (note that this is not equivalent to the angle of the complex amplitude). +* **freq** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The frequency of the square wave, in terms of 1 over sampling period. If not provided defaults to a single cycle (i.e :math:’frac\{1}\{text\{duration}}’). The frequency is limited to the range $\left(0,0.5\right]$ (the Nyquist frequency). +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.SymbolicPulse.md b/docs/api/qiskit/0.46/qiskit.pulse.library.SymbolicPulse.md new file mode 100644 index 00000000000..14388e5870c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.SymbolicPulse.md @@ -0,0 +1,258 @@ +--- +title: SymbolicPulse +description: API reference for qiskit.pulse.library.SymbolicPulse +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.SymbolicPulse +--- + +# SymbolicPulse + + + +`qiskit.pulse.library.SymbolicPulse(pulse_type, duration, parameters=None, name=None, limit_amplitude=None, envelope=None, constraints=None, valid_amp_conditions=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +Bases: `Pulse` + +The pulse representation model with parameters and symbolic expressions. + +A symbolic pulse instance can be defined with an envelope and parameter constraints. Envelope and parameter constraints should be provided as symbolic expressions. Rather than creating a subclass, different pulse shapes can be distinguished by the instance attributes [`SymbolicPulse.envelope`](#qiskit.pulse.library.SymbolicPulse.envelope "qiskit.pulse.library.SymbolicPulse.envelope") and [`SymbolicPulse.pulse_type`](#qiskit.pulse.library.SymbolicPulse.pulse_type "qiskit.pulse.library.SymbolicPulse.pulse_type"). + +The symbolic expressions must be defined either with [SymPy](https://www.sympy.org/en/index.html) or [Symengine](https://symengine.org). Usually Symengine-based expression is much more performant for instantiation of the [`SymbolicPulse`](#qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse"), however, it doesn’t support every functions available in SymPy. You may need to choose proper library depending on how you define your pulses. Symengine works in the most envelopes and constraints, and thus it is recommended to use this library especially when your program contains a lot of pulses. Also note that Symengine has the limited platform support and may not be available for your local system. Symengine is a required dependency for Qiskit on platforms that support it will always be installed along with Qiskit on macOS `x86_64` and `arm64`, and Linux `x86_64`, `aarch64`, and `ppc64le`. For 64-bit Windows users they will need to manual install it. For 32-bit platforms such as `i686` and `armv7` Linux, and on Linux `s390x` there are no pre-compiled packages available and to use symengine you’ll need to compile it from source. If Symengine is not available in your environment SymPy will be used. + +**Envelope function** + +The waveform at time $t$ is generated by the [`get_waveform()`](#qiskit.pulse.library.SymbolicPulse.get_waveform "qiskit.pulse.library.SymbolicPulse.get_waveform") according to + +$$ +F(t, \Theta) = \times F(t, {\rm duration}, \overline{\rm params}) +$$ + +where $\Theta$ is the set of full pulse parameters in the [`SymbolicPulse.parameters`](#qiskit.pulse.library.SymbolicPulse.parameters "qiskit.pulse.library.SymbolicPulse.parameters") dictionary which must include the $\rm duration$. Note that the $F$ is an envelope of the waveform, and a programmer must provide this as a symbolic expression. $\overline{\rm params}$ can be arbitrary complex values as long as they pass [`validate_parameters()`](#qiskit.pulse.library.SymbolicPulse.validate_parameters "qiskit.pulse.library.SymbolicPulse.validate_parameters") and your quantum backend can accept. The time $t$ and $\rm duration$ are in units of dt, i.e. sample time resolution, and this function is sampled with a discrete time vector in $[0, {\rm duration}]$ sampling the pulse envelope at every 0.5 dt (middle sampling strategy) when the [`SymbolicPulse.get_waveform()`](#qiskit.pulse.library.SymbolicPulse.get_waveform "qiskit.pulse.library.SymbolicPulse.get_waveform") method is called. The sample data is not generated until this method is called thus a symbolic pulse instance only stores parameter values and waveform shape, which greatly reduces memory footprint during the program generation. + +**Constraint functions** + +Constraints on the parameters are defined with an instance attribute [`SymbolicPulse.constraints`](#qiskit.pulse.library.SymbolicPulse.constraints "qiskit.pulse.library.SymbolicPulse.constraints") which can be provided through the constructor. The constraints value must be a symbolic expression, which is a function of parameters to be validated and must return a boolean value being `True` when parameters are valid. If there are multiple conditions to be evaluated, these conditions can be concatenated with logical expressions such as `And` and `Or` in SymPy or Symengine. The symbolic pulse instance can be played only when the constraint function returns `True`. The constraint is evaluated when [`validate_parameters()`](#qiskit.pulse.library.SymbolicPulse.validate_parameters "qiskit.pulse.library.SymbolicPulse.validate_parameters") is called. + +**Maximum amplitude validation** + +When you play a pulse in a quantum backend, you might face the restriction on the power that your waveform generator can handle. Usually, the pulse amplitude is normalized by this maximum power, namely $\max |F| \leq 1$. This condition is evaluated along with above constraints when you set `limit_amplitude = True` in the constructor. To evaluate maximum amplitude of the waveform, we need to call [`get_waveform()`](#qiskit.pulse.library.SymbolicPulse.get_waveform "qiskit.pulse.library.SymbolicPulse.get_waveform"). However, this introduces a significant overhead in the validation, and this cannot be ignored when you repeatedly instantiate symbolic pulse instances. [`SymbolicPulse.valid_amp_conditions`](#qiskit.pulse.library.SymbolicPulse.valid_amp_conditions "qiskit.pulse.library.SymbolicPulse.valid_amp_conditions") provides a condition to skip this waveform validation, and the waveform is not generated as long as this condition returns `True`, so that healthy symbolic pulses are created very quick. For example, for a simple pulse shape like `amp * cos(f * t)`, we know that pulse amplitude is valid as long as `amp` remains less than magnitude 1.0. So `abs(amp) <= 1` could be passed as [`SymbolicPulse.valid_amp_conditions`](#qiskit.pulse.library.SymbolicPulse.valid_amp_conditions "qiskit.pulse.library.SymbolicPulse.valid_amp_conditions") to skip doing a full waveform evaluation for amplitude validation. This expression is provided through the constructor. If this is not provided, the waveform is generated everytime when [`validate_parameters()`](#qiskit.pulse.library.SymbolicPulse.validate_parameters "qiskit.pulse.library.SymbolicPulse.validate_parameters") is called. + +**Examples** + +This is how a user can instantiate a symbolic pulse instance. In this example, we instantiate a custom Sawtooth envelope. + +```python +from qiskit.pulse.library import SymbolicPulse + +my_pulse = SymbolicPulse( + pulse_type="Sawtooth", + duration=100, + parameters={"amp": 0.1, "freq": 0.05}, + name="pulse1", +) +``` + +Note that [`SymbolicPulse`](#qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") can be instantiated without providing the envelope and constraints. However, this instance cannot generate waveforms without knowing the envelope definition. Now you need to provide the envelope. + +```python +import sympy +from qiskit.pulse.library import SymbolicPulse + +t, amp, freq = sympy.symbols("t, amp, freq") +envelope = 2 * amp * (freq * t - sympy.floor(1 / 2 + freq * t)) + +my_pulse = SymbolicPulse( + pulse_type="Sawtooth", + duration=100, + parameters={"amp": 0.1, "freq": 0.05}, + envelope=envelope, + name="pulse1", +) + +my_pulse.draw() +``` + +![../\_images/qiskit-pulse-library-SymbolicPulse-1.png](/images/api/qiskit/0.46/qiskit-pulse-library-SymbolicPulse-1.png) + +Likewise, you can define [`SymbolicPulse.constraints`](#qiskit.pulse.library.SymbolicPulse.constraints "qiskit.pulse.library.SymbolicPulse.constraints") for `my_pulse`. After providing the envelope definition, you can generate the waveform data. Note that it would be convenient to define a factory function that automatically accomplishes this procedure. + +```python +def Sawtooth(duration, amp, freq, name): + t, amp, freq = sympy.symbols("t, amp, freq") + + instance = SymbolicPulse( + pulse_type="Sawtooth", + duration=duration, + parameters={"amp": amp, "freq": freq}, + envelope=2 * amp * (freq * t - sympy.floor(1 / 2 + freq * t)), + name=name, + ) + + return instance +``` + +You can also provide a `Parameter` object in the `parameters` dictionary, or define `duration` with a `Parameter` object when you instantiate the symbolic pulse instance. A waveform cannot be generated until you assign all unbounded parameters. Note that parameters will be assigned through the schedule playing the pulse. + +**Serialization** + +The [`SymbolicPulse`](#qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") subclass can be serialized along with the symbolic expressions through [`qiskit.qpy`](qpy#module-qiskit.qpy "qiskit.qpy"). A user can therefore create a custom pulse subclass with a novel envelope and constraints, and then one can instantiate the class with certain parameters to run on a backend. This pulse instance can be saved in the QPY binary, which can be loaded afterwards even within the environment not having original class definition loaded. This mechanism also allows us to easily share a pulse program including custom pulse instructions with collaborators. + +Create a parametric pulse. + +**Parameters** + +* **pulse\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Display name of this pulse shape. +* **duration** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Duration of pulse. +* **parameters** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*] | None*) – Dictionary of pulse parameters that defines the pulse envelope. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this particular pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the absolute value of the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. +* **envelope** (*Expr | None*) – Pulse envelope expression. +* **constraints** (*Expr | None*) – Pulse parameter constraint expression. +* **valid\_amp\_conditions** (*Expr | None*) – Extra conditions to skip a full-waveform check for the amplitude limit. If this condition is not met, then the validation routine will investigate the full-waveform and raise an error when the amplitude norm of any data point exceeds 1.0. If not provided, the validation always creates a full-waveform. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When not all parameters are listed in the attribute `PARAM_DEF`. + +## Attributes + + + +### constraints + +Return symbolic expression for the pulse parameter constraints. + + + +### duration + + + +### envelope + +Return symbolic expression for the pulse envelope. + + + +### id + +Unique identifier for this pulse. + + + +### limit\_amplitude + +`= True` + + + +### name + + + +### parameters + + + +### pulse\_type + +Return display name of the pulse shape. + + + +### valid\_amp\_conditions + +Return symbolic expression for the pulse amplitude constraints. + +## Methods + +### draw + + + +`draw(style=None, backend=None, time_range=None, time_unit='dt', show_waveform_info=True, plotter='mpl2d', axis=None)` + +Plot the interpolated envelope of pulse. + +**Parameters** + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. + +* **backend** (*Optional\[BaseBackend]*) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple `(tmin, tmax)`. + +* **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either `dt` or `ns`. The unit of `ns` is available only when `backend` object is provided. + +* **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show waveform annotations, i.e. name, of waveforms. Set `True` to show additional information about waveforms. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl2d: Matplotlib API for 2D image generation. + Matplotlib API to generate 2D image. Charts are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as `axis` input. + ``` + + axis and style kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given `axis` instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details. + +**Returns** + +Visualization output data. The returned data type depends on the `plotter`. If matplotlib family is specified, this will be a `matplotlib.pyplot.Figure` data. + +### get\_waveform + + + +`get_waveform()` + +Return a Waveform with samples filled according to the formula that the pulse represents and the parameter values it contains. + +Since the returned array is a discretized time series of the continuous function, this method uses a midpoint sampler. For `duration`, return: + +$$ +\{f(t+0.5) \in \mathbb{C} | t \in \mathbb{Z} \wedge 0<=t<\texttt{duration}\} +$$ + +**Returns** + +A waveform representation of this pulse. + +**Raises** + +* [**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When parameters are not assigned. +* [**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When expression for pulse envelope is not assigned. + +**Return type** + +[*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### validate\_parameters + + + +`validate_parameters()` + +Validate parameters. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the parameters passed are not valid. + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Triangle_class.rst.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Triangle_class.rst.md new file mode 100644 index 00000000000..e2ee9f33ae5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Triangle_class.rst.md @@ -0,0 +1,44 @@ +--- +title: Triangle +description: API reference for qiskit.pulse.library.Triangle +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.Triangle +--- + + + +# qiskit.pulse.library.Triangle + + + +`qiskit.pulse.library.Triangle(duration, amp, phase, freq=None, angle=0.0, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +A triangle wave pulse. + +The envelope of the pulse is given by: + +$$ +f(x) = \text{A}\left[\text{sawtooth}\left(x\right)\right] , 0 <= x < duration +$$ + +where $\text{A} = \text{amp} \times\exp\left(i\times\text{angle}\right)$, and $\text{sawtooth}\left(x\right)$ is a sawtooth wave with the same frequency as the triangle wave, but a phase shifted by $\frac{\pi}{2}$. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The magnitude of the amplitude of the triangle wave. Wave range is \[-amp,\`amp\`]. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The phase of the triangle wave (note that this is not equivalent to the angle of the complex amplitude) +* **freq** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The frequency of the triangle wave, in terms of 1 over sampling period. If not provided defaults to a single cycle (i.e :math:’frac\{1}\{text\{duration}}’). The frequency is limited to the range $\left(0,0.5\right]$ (the Nyquist frequency). +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the pulse. Default value 0. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Return type** + +*ScalableSymbolicPulse* + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.Waveform.md b/docs/api/qiskit/0.46/qiskit.pulse.library.Waveform.md new file mode 100644 index 00000000000..f2b8f6b35f2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.Waveform.md @@ -0,0 +1,113 @@ +--- +title: Waveform +description: API reference for qiskit.pulse.library.Waveform +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.library.Waveform +--- + +# Waveform + + + +`qiskit.pulse.library.Waveform(samples, name=None, epsilon=1e-07, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/waveform.py "view source code") + +Bases: `Pulse` + +A pulse specified completely by complex-valued samples; each sample is played for the duration of the backend cycle-time, dt. + +Create new sample pulse command. + +**Parameters** + +* **samples** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]*) – Complex array of the samples in the pulse envelope. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Unique name to identify the pulse. +* **epsilon** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Pulse sample norm tolerance for clipping. If any sample’s norm exceeds unity by less than or equal to epsilon it will be clipped to unit norm. If the sample norm is greater than 1+epsilon an error will be raised. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – Passed to parent Pulse + +## Attributes + + + +### duration + + + +### name + + + +### id + +Unique identifier for this pulse. + + + +### limit\_amplitude + +`= True` + + + +### parameters + +Return a dictionary containing the pulse’s parameters. + + + +### samples + +Return sample values. + +## Methods + +### draw + + + +`draw(style=None, backend=None, time_range=None, time_unit='dt', show_waveform_info=True, plotter='mpl2d', axis=None)` + +Plot the interpolated envelope of pulse. + +**Parameters** + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. + +* **backend** (*Optional\[BaseBackend]*) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple `(tmin, tmax)`. + +* **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either `dt` or `ns`. The unit of `ns` is available only when `backend` object is provided. + +* **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show waveform annotations, i.e. name, of waveforms. Set `True` to show additional information about waveforms. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl2d: Matplotlib API for 2D image generation. + Matplotlib API to generate 2D image. Charts are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as `axis` input. + ``` + + axis and style kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given `axis` instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details. + +**Returns** + +Visualization output data. The returned data type depends on the `plotter`. If matplotlib family is specified, this will be a `matplotlib.pyplot.Figure` data. + +### is\_parameterized + + + +`is_parameterized()` + +Return True iff the instruction is parameterized. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.library.gaussian_square_echo.md b/docs/api/qiskit/0.46/qiskit.pulse.library.gaussian_square_echo.md new file mode 100644 index 00000000000..80c17b389ff --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.library.gaussian_square_echo.md @@ -0,0 +1,77 @@ +--- +title: gaussian_square_echo +description: API reference for qiskit.pulse.library.gaussian_square_echo +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.pulse.library.gaussian_square_echo +--- + + + +# qiskit.pulse.library.gaussian\_square\_echo + + + +`qiskit.pulse.library.gaussian_square_echo(duration, amp, sigma, width=None, angle=0.0, active_amp=0.0, active_angle=0.0, risefall_sigma_ratio=None, name=None, limit_amplitude=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/library/symbolic_pulses.py "view source code") + +An echoed Gaussian square pulse with an active tone overlaid on it. + +The Gaussian Square Echo pulse is composed of three pulses. First, a Gaussian Square pulse $f_{echo}(x)$ with amplitude `amp` and phase `angle` playing for half duration, followed by a second Gaussian Square pulse $-f_{echo}(x)$ with opposite amplitude and same phase playing for the rest of the duration. Third a Gaussian Square pulse $f_{active}(x)$ with amplitude `active_amp` and phase `active_angle` playing for the entire duration. The Gaussian Square Echo pulse $g_e()$ can be written as: + +$$ +\begin{aligned} +g_e(x) &= \begin{cases} f_{\text{active}} + f_{\text{echo}}(x) & x < \frac{\text{duration}}{2}\\ + f_{\text{active}} - f_{\text{echo}}(x) & \frac{\text{duration}}{2} < x \end{cases}\\ +\end{aligned} +$$ + +One case where this pulse can be used is when implementing a direct CNOT gate with a cross-resonance superconducting qubit architecture. When applying this pulse to the target qubit, the active portion can be used to cancel IX terms from the cross-resonance drive while the echo portion can reduce the impact of a static ZZ coupling. + +Exactly one of the `risefall_sigma_ratio` and `width` parameters has to be specified. + +If `risefall_sigma_ratio` is not `None` and `width` is `None`: + +$$ +\begin{aligned} +\text{risefall} &= \text{risefall\_sigma\_ratio} \times \text{sigma}\\ +\text{width} &= \text{duration} - 2 \times \text{risefall} +\end{aligned} +$$ + +If `width` is not None and `risefall_sigma_ratio` is None: + +$$ +\text{risefall} = \frac{\text{duration} - \text{width}}{2} + + +$$ + +**References** + +1. [*Jurcevic, P., Javadi-Abhari, A., Bishop, L. S., Lauer, I., Bogorin, D. F., Brink, M., Capelluto, L., G\{“u}nl\{“u}k, O., Itoko, T., Kanazawa, N. & others Demonstration of quantum volume 64 on a superconducting quantum computing system. (Section V)*](https://iopscience.iop.org/article/10.1088/2058-9565/abe519) + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Pulse length in terms of the sampling period dt. +* **amp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – The amplitude of the rise and fall and of the echoed pulse. +* **sigma** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – A measure of how wide or narrow the risefall is; see the class docstring for more details. +* **width** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The duration of the embedded square pulse. +* **angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radians of the complex phase factor uniformly scaling the echoed pulse. Default value 0. +* **active\_amp** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The amplitude of the active pulse. +* **active\_angle** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The angle in radian of the complex phase factor uniformly scaling the active pulse. Default value 0. +* **risefall\_sigma\_ratio** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The ratio of each risefall duration to sigma. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Display name for this pulse envelope. +* **limit\_amplitude** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If `True`, then limit the amplitude of the waveform to 1. The default is `True` and the amplitude is constrained to 1. + +**Returns** + +ScalableSymbolicPulse instance. + +**Raises** + +[**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When width and risefall\_sigma\_ratio are both empty or both non-empty. + +**Return type** + +[*SymbolicPulse*](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.symbolic_pulses.SymbolicPulse") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignEquispaced.md b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignEquispaced.md new file mode 100644 index 00000000000..5c220683540 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignEquispaced.md @@ -0,0 +1,62 @@ +--- +title: AlignEquispaced +description: API reference for qiskit.pulse.transforms.AlignEquispaced +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.transforms.AlignEquispaced +--- + +# AlignEquispaced + + + +`qiskit.pulse.transforms.AlignEquispaced(duration)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/alignments.py "view source code") + +Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +Align instructions with equispaced interval within a specified duration. + +Instructions played on different channels are also arranged in a sequence. This alignment is convenient to create dynamical decoupling sequences such as PDD. + +Create new equispaced context. + +**Parameters** + +**duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Duration of this context. This should be larger than the schedule duration. If the specified duration is shorter than the schedule duration, no alignment is performed and the input schedule is just returned. This duration can be parametrized. + +## Attributes + + + +### duration + +Return context duration. + + + +### is\_sequential + +## Methods + +### align + + + +`align(schedule)` + +Reallocate instructions according to the policy. + +Only top-level sub-schedules are aligned. If sub-schedules are nested, nested schedules are not recursively aligned. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Schedule to align. + +**Returns** + +Schedule with reallocated instructions. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignFunc.md b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignFunc.md new file mode 100644 index 00000000000..9f1a159ff4b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignFunc.md @@ -0,0 +1,82 @@ +--- +title: AlignFunc +description: API reference for qiskit.pulse.transforms.AlignFunc +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.transforms.AlignFunc +--- + +# AlignFunc + + + +`qiskit.pulse.transforms.AlignFunc(duration, func)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/alignments.py "view source code") + +Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +Allocate instructions at position specified by callback function. + +The position is specified for each instruction of index `j` as a fractional coordinate in \[0, 1] within the specified duration. + +Instructions played on different channels are also arranged in a sequence. This alignment is convenient to create dynamical decoupling sequences such as UDD. + +For example, UDD sequence with 10 pulses can be specified with following function. + +```python +def udd10_pos(j): +return np.sin(np.pi*j/(2*10 + 2))**2 +``` + + + This context cannot be QPY serialized because of the callable. If you use this context, your program cannot be saved in QPY format. + + +Create new equispaced context. + +**Parameters** + +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression")) – Duration of this context. This should be larger than the schedule duration. If the specified duration is shorter than the schedule duration, no alignment is performed and the input schedule is just returned. This duration can be parametrized. +* **func** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")) – A function that takes an index of sub-schedule and returns the fractional coordinate of of that sub-schedule. The returned value should be defined within \[0, 1]. The pulse index starts from 1. + +## Attributes + + + +### duration + +Return context duration. + + + +### func + +Return context alignment function. + + + +### is\_sequential + +## Methods + +### align + + + +`align(schedule)` + +Reallocate instructions according to the policy. + +Only top-level sub-schedules are aligned. If sub-schedules are nested, nested schedules are not recursively aligned. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Schedule to align. + +**Returns** + +Schedule with reallocated instructions. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignLeft.md b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignLeft.md new file mode 100644 index 00000000000..913fff433db --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignLeft.md @@ -0,0 +1,52 @@ +--- +title: AlignLeft +description: API reference for qiskit.pulse.transforms.AlignLeft +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.transforms.AlignLeft +--- + +# AlignLeft + + + +`qiskit.pulse.transforms.AlignLeft`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/alignments.py "view source code") + +Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +Align instructions in as-soon-as-possible manner. + +Instructions are placed at earliest available timeslots. + +Create new left-justified context. + +## Attributes + + + +### is\_sequential + +## Methods + +### align + + + +`align(schedule)` + +Reallocate instructions according to the policy. + +Only top-level sub-schedules are aligned. If sub-schedules are nested, nested schedules are not recursively aligned. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Schedule to align. + +**Returns** + +Schedule with reallocated instructions. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignRight.md b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignRight.md new file mode 100644 index 00000000000..63beef9db7b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignRight.md @@ -0,0 +1,52 @@ +--- +title: AlignRight +description: API reference for qiskit.pulse.transforms.AlignRight +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.transforms.AlignRight +--- + +# AlignRight + + + +`qiskit.pulse.transforms.AlignRight`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/alignments.py "view source code") + +Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +Align instructions in as-late-as-possible manner. + +Instructions are placed at latest available timeslots. + +Create new right-justified context. + +## Attributes + + + +### is\_sequential + +## Methods + +### align + + + +`align(schedule)` + +Reallocate instructions according to the policy. + +Only top-level sub-schedules are aligned. If sub-schedules are nested, nested schedules are not recursively aligned. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Schedule to align. + +**Returns** + +Schedule with reallocated instructions. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignSequential.md b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignSequential.md new file mode 100644 index 00000000000..30e2864a2d6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.pulse.transforms.AlignSequential.md @@ -0,0 +1,52 @@ +--- +title: AlignSequential +description: API reference for qiskit.pulse.transforms.AlignSequential +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.pulse.transforms.AlignSequential +--- + +# AlignSequential + + + +`qiskit.pulse.transforms.AlignSequential`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/pulse/transforms/alignments.py "view source code") + +Bases: [`AlignmentKind`](pulse#qiskit.pulse.transforms.AlignmentKind "qiskit.pulse.transforms.alignments.AlignmentKind") + +Align instructions sequentially. + +Instructions played on different channels are also arranged in a sequence. No buffer time is inserted in between instructions. + +Create new sequential context. + +## Attributes + + + +### is\_sequential + +## Methods + +### align + + + +`align(schedule)` + +Reallocate instructions according to the policy. + +Only top-level sub-schedules are aligned. If sub-schedules are nested, nested schedules are not recursively aligned. + +**Parameters** + +**schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")) – Schedule to align. + +**Returns** + +Schedule with reallocated instructions. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.GateCalibration.md b/docs/api/qiskit/0.46/qiskit.qobj.GateCalibration.md new file mode 100644 index 00000000000..7d83034a566 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.GateCalibration.md @@ -0,0 +1,65 @@ +--- +title: GateCalibration +description: API reference for qiskit.qobj.GateCalibration +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.GateCalibration +--- + +# GateCalibration + + + +`qiskit.qobj.GateCalibration(name, qubits, params, instructions)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Each calibration specifies a unique gate by name, qubits and params, and contains the Pulse instructions to implement it. + +Initialize a single gate calibration. Instructions may reference waveforms which should be made available in the pulse\_library. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Gate name. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*)*) – Qubits the gate applies to. +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*)*) – Gate parameter values, if any. +* **instructions** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*PulseQobjInstruction*](qiskit.qobj.PulseQobjInstruction "qiskit.qobj.PulseQobjInstruction")*)*) – The gate implementation. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new GateCalibration object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the GateCalibration to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.GateCalibration.to_dict "qiskit.qobj.GateCalibration.to_dict"). + +**Returns** + +The GateCalibration from the input dictionary. + +**Return type** + +[GateCalibration](#qiskit.qobj.GateCalibration "qiskit.qobj.GateCalibration") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Gate Calibration. + +**Returns** + +The dictionary form of the GateCalibration. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.PulseLibraryItem.md b/docs/api/qiskit/0.46/qiskit.qobj.PulseLibraryItem.md new file mode 100644 index 00000000000..3d607960751 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.PulseLibraryItem.md @@ -0,0 +1,63 @@ +--- +title: PulseLibraryItem +description: API reference for qiskit.qobj.PulseLibraryItem +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.PulseLibraryItem +--- + +# PulseLibraryItem + + + +`qiskit.qobj.PulseLibraryItem(name, samples)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +An item in a pulse library. + +Instantiate a pulse library item. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A name for the pulse. +* **samples** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]*) – A list of complex values defining pulse shape. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new PulseLibraryItem object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the experiment config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[PulseLibraryItem](#qiskit.qobj.PulseLibraryItem "qiskit.qobj.PulseLibraryItem") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the pulse library item. + +**Returns** + +The dictionary form of the PulseLibraryItem. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.PulseQobj.md b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobj.md new file mode 100644 index 00000000000..decbaddfd3a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobj.md @@ -0,0 +1,84 @@ +--- +title: PulseQobj +description: API reference for qiskit.qobj.PulseQobj +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.PulseQobj +--- + +# PulseQobj + + + +`qiskit.qobj.PulseQobj(qobj_id, config, experiments, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A Pulse Qobj. + +Instantiate a new Pulse Qobj Object. + +Each Pulse Qobj object is used to represent a single payload that will be passed to a Qiskit provider. It mirrors the Qobj the published [Qobj specification](https://arxiv.org/abs/1809.03452) for Pulse experiments. + +**Parameters** + +* **qobj\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An identifier for the qobj +* **config** ([*PulseQobjConfig*](qiskit.qobj.PulseQobjConfig "qiskit.qobj.PulseQobjConfig")) – A config for the entire run +* **header** ([*QobjHeader*](qiskit.qobj.QobjHeader "qiskit.qobj.QobjHeader")) – A header for the entire run +* **experiments** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of lists of [`PulseQobjExperiment`](qiskit.qobj.PulseQobjExperiment "qiskit.qobj.PulseQobjExperiment") objects representing an experiment + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new PulseQobj object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the PulseQobj to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.PulseQobj.to_dict "qiskit.qobj.PulseQobj.to_dict"). + +**Returns** + +The PulseQobj from the input dictionary. + +**Return type** + +[PulseQobj](#qiskit.qobj.PulseQobj "qiskit.qobj.PulseQobj") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Pulse Qobj. + +Note this dict is not in the json wire format expected by IBMQ and qobj specification because complex numbers are still of type complex. Also this may contain native numpy arrays. When serializing this output for use with IBMQ you can leverage a json encoder that converts these as expected. For example: + +```python +import json +import numpy + +class QobjEncoder(json.JSONEncoder): + def default(self, obj): + if isinstance(obj, numpy.ndarray): + return obj.tolist() + if isinstance(obj, complex): + return (obj.real, obj.imag) + return json.JSONEncoder.default(self, obj) + +json.dumps(qobj.to_dict(), cls=QobjEncoder) +``` + +**Returns** + +A dictionary representation of the PulseQobj object + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjConfig.md b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjConfig.md new file mode 100644 index 00000000000..f0d15776ff7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjConfig.md @@ -0,0 +1,73 @@ +--- +title: PulseQobjConfig +description: API reference for qiskit.qobj.PulseQobjConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.PulseQobjConfig +--- + +# PulseQobjConfig + + + +`qiskit.qobj.PulseQobjConfig(meas_level, meas_return, pulse_library, qubit_lo_freq, meas_lo_freq, memory_slot_size=None, rep_time=None, rep_delay=None, shots=None, seed_simulator=None, memory_slots=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: `QobjDictField` + +A configuration for a Pulse Qobj. + +Instantiate a PulseQobjConfig object. + +**Parameters** + +* **meas\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The measurement level to use. +* **meas\_return** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The level of measurement information to return. +* **pulse\_library** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of [`PulseLibraryItem`](qiskit.qobj.PulseLibraryItem "qiskit.qobj.PulseLibraryItem") objects which define the set of primitive pulses +* **qubit\_lo\_freq** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of frequencies (as floats) for the qubit driver LO’s in GHz. +* **meas\_lo\_freq** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of frequencies (as floats) for the’ measurement driver LO’s in GHz. +* **memory\_slot\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Size of each memory slot if the output is Level 0. +* **rep\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time per program execution in sec. Must be from the list provided by the backend (`backend.configuration().rep_times`). Defaults to the first entry in `backend.configuration().rep_times`. +* **rep\_delay** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Delay between programs in sec. Only supported on certain backends (`backend.configuration().dynamic_reprate_enabled` ). If supported, `rep_delay` will be used instead of `rep_time` and must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is `backend.configuration().default_rep_delay`. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of shots +* **seed\_simulator** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the seed to use in the simulator +* **memory\_slots** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The number of memory slots on the device +* **kwargs** – Additional free form key value fields to add to the configuration + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new PulseQobjConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[PulseQobjConfig](#qiskit.qobj.PulseQobjConfig "qiskit.qobj.PulseQobjConfig") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Pulse Qobj config. + +**Returns** + +The dictionary form of the PulseQobjConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperiment.md b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperiment.md new file mode 100644 index 00000000000..bf4b7534b2a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperiment.md @@ -0,0 +1,66 @@ +--- +title: PulseQobjExperiment +description: API reference for qiskit.qobj.PulseQobjExperiment +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.PulseQobjExperiment +--- + +# PulseQobjExperiment + + + +`qiskit.qobj.PulseQobjExperiment(instructions, config=None, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A Pulse Qobj Experiment. + +Each instance of this class is used to represent an individual Pulse experiment as part of a larger Pulse Qobj. + +Instantiate a PulseQobjExperiment. + +**Parameters** + +* **config** ([*PulseQobjExperimentConfig*](qiskit.qobj.PulseQobjExperimentConfig "qiskit.qobj.PulseQobjExperimentConfig")) – A config object for the experiment +* **header** (*PulseQobjExperimentHeader*) – A header object for the experiment +* **instructions** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of [`PulseQobjInstruction`](qiskit.qobj.PulseQobjInstruction "qiskit.qobj.PulseQobjInstruction") objects + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new PulseQobjExperiment object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the experiment config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[PulseQobjExperiment](#qiskit.qobj.PulseQobjExperiment "qiskit.qobj.PulseQobjExperiment") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Experiment. + +**Returns** + +The dictionary form of the PulseQobjExperiment. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperimentConfig.md b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperimentConfig.md new file mode 100644 index 00000000000..6233282afa2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjExperimentConfig.md @@ -0,0 +1,64 @@ +--- +title: PulseQobjExperimentConfig +description: API reference for qiskit.qobj.PulseQobjExperimentConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.PulseQobjExperimentConfig +--- + +# PulseQobjExperimentConfig + + + +`qiskit.qobj.PulseQobjExperimentConfig(qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: `QobjDictField` + +A config for a single Pulse experiment in the qobj. + +Instantiate a PulseQobjExperimentConfig object. + +**Parameters** + +* **qubit\_lo\_freq** (*List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of qubit LO frequencies in GHz. +* **meas\_lo\_freq** (*List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of meas readout LO frequencies in GHz. +* **kwargs** – Additional free form key value fields to add to the configuration + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QobjHeader object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the QobjHeader to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.PulseQobjExperimentConfig.to_dict "qiskit.qobj.PulseQobjExperimentConfig.to_dict"). + +**Returns** + +The QobjDictField from the input dictionary. + +**Return type** + +QobjDictFieldr + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the OpenQASM 2 Qobj. + +**Returns** + +The dictionary form of the QobjHeader. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjInstruction.md b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjInstruction.md new file mode 100644 index 00000000000..a10e26aa2e6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.PulseQobjInstruction.md @@ -0,0 +1,78 @@ +--- +title: PulseQobjInstruction +description: API reference for qiskit.qobj.PulseQobjInstruction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.PulseQobjInstruction +--- + +# PulseQobjInstruction + + + +`qiskit.qobj.PulseQobjInstruction(name, t0, ch=None, conditional=None, val=None, phase=None, duration=None, qubits=None, memory_slot=None, register_slot=None, kernels=None, discriminators=None, label=None, type=None, pulse_shape=None, parameters=None, frequency=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A class representing a single instruction in an PulseQobj Experiment. + +Instantiate a new PulseQobjInstruction object. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the instruction +* **t0** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Pulse start time in integer **dt** units. +* **ch** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The channel to apply the pulse instruction. +* **conditional** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The register to use for a conditional for this instruction +* **val** ([*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")) – Complex value to apply, bounded by an absolute value of 1. +* **phase** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – if a `fc` instruction, the frame change phase in radians. +* **frequency** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – if a `sf` instruction, the frequency in Hz. +* **duration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The duration of the pulse in **dt** units. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of `int` representing the qubits the instruction operates on +* **memory\_slot** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – If a `measure` instruction this is a list of `int` containing the list of memory slots to store the measurement results in (must be the same length as qubits). If a `bfunc` instruction this is a single `int` of the memory slot to store the boolean function result in. +* **register\_slot** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – If a `measure` instruction this is a list of `int` containing the list of register slots in which to store the measurement results (must be the same length as qubits). If a `bfunc` instruction this is a single `int` of the register slot in which to store the result. +* **kernels** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of [`QobjMeasurementOption`](qiskit.qobj.QobjMeasurementOption "qiskit.qobj.QobjMeasurementOption") objects defining the measurement kernels and set of parameters if the measurement level is 1 or 2. Only used for `acquire` instructions. +* **discriminators** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of [`QobjMeasurementOption`](qiskit.qobj.QobjMeasurementOption "qiskit.qobj.QobjMeasurementOption") used to set the discriminators to be used if the measurement level is 2. Only used for `acquire` instructions. +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Label of instruction +* **type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Type of instruction +* **pulse\_shape** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The shape of the parametric pulse +* **parameters** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The parameters for a parametric pulse + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new PulseQobjExperimentConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the experiment config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[PulseQobjInstruction](#qiskit.qobj.PulseQobjInstruction "qiskit.qobj.PulseQobjInstruction") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Instruction. + +**Returns** + +The dictionary form of the PulseQobjInstruction. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QasmExperimentCalibrations.md b/docs/api/qiskit/0.46/qiskit.qobj.QasmExperimentCalibrations.md new file mode 100644 index 00000000000..a1bfe465e57 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QasmExperimentCalibrations.md @@ -0,0 +1,62 @@ +--- +title: QasmExperimentCalibrations +description: API reference for qiskit.qobj.QasmExperimentCalibrations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QasmExperimentCalibrations +--- + +# QasmExperimentCalibrations + + + +`qiskit.qobj.QasmExperimentCalibrations(gates)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A container for any calibrations data. The gates attribute contains a list of GateCalibrations. + +Initialize a container for calibrations. + +**Parameters** + +**gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*GateCalibration*](qiskit.qobj.GateCalibration "qiskit.qobj.GateCalibration")*)*) – + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new GateCalibration object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the QasmExperimentCalibrations to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.QasmExperimentCalibrations.to_dict "qiskit.qobj.QasmExperimentCalibrations.to_dict"). + +**Returns** + +The QasmExperimentCalibrations from the input dictionary. + +**Return type** + +[QasmExperimentCalibrations](#qiskit.qobj.QasmExperimentCalibrations "qiskit.qobj.QasmExperimentCalibrations") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the calibrations. + +**Returns** + +The dictionary form of the GateCalibration. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QasmQobj.md b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobj.md new file mode 100644 index 00000000000..fa3039bb4eb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobj.md @@ -0,0 +1,84 @@ +--- +title: QasmQobj +description: API reference for qiskit.qobj.QasmQobj +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QasmQobj +--- + +# QasmQobj + + + +`qiskit.qobj.QasmQobj(qobj_id=None, config=None, experiments=None, header=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +An OpenQASM 2 Qobj. + +Instantiate a new OpenQASM 2 Qobj Object. + +Each OpenQASM 2 Qobj object is used to represent a single payload that will be passed to a Qiskit provider. It mirrors the Qobj the published [Qobj specification](https://arxiv.org/abs/1809.03452) for OpenQASM experiments. + +**Parameters** + +* **qobj\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An identifier for the qobj +* **config** (*QasmQobjRunConfig*) – A config for the entire run +* **header** ([*QobjHeader*](qiskit.qobj.QobjHeader "qiskit.qobj.QobjHeader")) – A header for the entire run +* **experiments** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of lists of [`QasmQobjExperiment`](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment") objects representing an experiment + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QASMQobj object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the QasmQobj to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.QasmQobj.to_dict "qiskit.qobj.QasmQobj.to_dict"). + +**Returns** + +The QasmQobj from the input dictionary. + +**Return type** + +[QasmQobj](#qiskit.qobj.QasmQobj "qiskit.qobj.QasmQobj") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the OpenQASM 2 Qobj. + +Note this dict is not in the json wire format expected by IBM and Qobj specification because complex numbers are still of type complex. Also, this may contain native numpy arrays. When serializing this output for use with IBM systems, you can leverage a json encoder that converts these as expected. For example: + +```python +import json +import numpy + +class QobjEncoder(json.JSONEncoder): + def default(self, obj): + if isinstance(obj, numpy.ndarray): + return obj.tolist() + if isinstance(obj, complex): + return (obj.real, obj.imag) + return json.JSONEncoder.default(self, obj) + +json.dumps(qobj.to_dict(), cls=QobjEncoder) +``` + +**Returns** + +A dictionary representation of the QasmQobj object + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjConfig.md b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjConfig.md new file mode 100644 index 00000000000..85d12ad1dd5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjConfig.md @@ -0,0 +1,75 @@ +--- +title: QasmQobjConfig +description: API reference for qiskit.qobj.QasmQobjConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QasmQobjConfig +--- + +# QasmQobjConfig + + + +`qiskit.qobj.QasmQobjConfig(shots=None, seed_simulator=None, memory=None, parameter_binds=None, meas_level=None, meas_return=None, memory_slots=None, n_qubits=None, pulse_library=None, calibrations=None, rep_delay=None, qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: [`SimpleNamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace "(in Python v3.12)") + +A configuration for an OpenQASM 2 Qobj. + +Model for RunConfig. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of shots. +* **seed\_simulator** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the seed to use in the simulator +* **memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to request memory from backend (per-shot readouts) +* **parameter\_binds** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*]*) – List of parameter bindings +* **meas\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Measurement level 0, 1, or 2 +* **meas\_return** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – For measurement level \< 2, whether single or avg shots are returned +* **memory\_slots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of memory slots on the device +* **n\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits on the device +* **pulse\_library** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of [`PulseLibraryItem`](qiskit.qobj.PulseLibraryItem "qiskit.qobj.PulseLibraryItem"). +* **calibrations** ([*QasmExperimentCalibrations*](qiskit.qobj.QasmExperimentCalibrations "qiskit.qobj.QasmExperimentCalibrations")) – Information required for Pulse gates. +* **rep\_delay** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Delay between programs in sec. Only supported on certain backends (`backend.configuration().dynamic_reprate_enabled` ). Must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is `backend.configuration().default_rep_delay`. +* **qubit\_lo\_freq** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of frequencies (as floats) for the qubit driver LO’s in GHz. +* **meas\_lo\_freq** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of frequencies (as floats) for the measurement driver LO’s in GHz. +* **kwargs** – Additional free form key value fields to add to the configuration. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QasmQobjConfig object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[QasmQobjConfig](#qiskit.qobj.QasmQobjConfig "qiskit.qobj.QasmQobjConfig") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the OpenQASM 2 Qobj config. + +**Returns** + +The dictionary form of the QasmQobjConfig. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperiment.md b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperiment.md new file mode 100644 index 00000000000..2f88fa0a5fa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperiment.md @@ -0,0 +1,66 @@ +--- +title: QasmQobjExperiment +description: API reference for qiskit.qobj.QasmQobjExperiment +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QasmQobjExperiment +--- + +# QasmQobjExperiment + + + +`qiskit.qobj.QasmQobjExperiment(config=None, header=None, instructions=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +An OpenQASM 2 Qobj Experiment. + +Each instance of this class is used to represent an OpenQASM 2 experiment as part of a larger OpenQASM 2 qobj. + +Instantiate a QasmQobjExperiment. + +**Parameters** + +* **config** ([*QasmQobjExperimentConfig*](qiskit.qobj.QasmQobjExperimentConfig "qiskit.qobj.QasmQobjExperimentConfig")) – A config object for the experiment +* **header** (*QasmQobjExperimentHeader*) – A header object for the experiment +* **instructions** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of [`QasmQobjInstruction`](qiskit.qobj.QasmQobjInstruction "qiskit.qobj.QasmQobjInstruction") objects + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QasmQobjExperiment object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the experiment config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[QasmQobjExperiment](#qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Experiment. + +**Returns** + +The dictionary form of the QasmQObjExperiment. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperimentConfig.md b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperimentConfig.md new file mode 100644 index 00000000000..1f0b1641370 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjExperimentConfig.md @@ -0,0 +1,63 @@ +--- +title: QasmQobjExperimentConfig +description: API reference for qiskit.qobj.QasmQobjExperimentConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QasmQobjExperimentConfig +--- + +# QasmQobjExperimentConfig + + + +`qiskit.qobj.QasmQobjExperimentConfig(calibrations=None, qubit_lo_freq=None, meas_lo_freq=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: `QobjDictField` + +Configuration for a single OpenQASM 2 experiment in the qobj. + +**Parameters** + +* **calibrations** ([*QasmExperimentCalibrations*](qiskit.qobj.QasmExperimentCalibrations "qiskit.qobj.QasmExperimentCalibrations")) – Information required for Pulse gates. +* **qubit\_lo\_freq** (*List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of qubit LO frequencies in GHz. +* **meas\_lo\_freq** (*List\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – List of meas readout LO frequencies in GHz. +* **kwargs** – Additional free form key value fields to add to the configuration + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QobjHeader object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the QobjHeader to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.QasmQobjExperimentConfig.to_dict "qiskit.qobj.QasmQobjExperimentConfig.to_dict"). + +**Returns** + +The QobjDictField from the input dictionary. + +**Return type** + +QobjDictFieldr + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the OpenQASM 2 Qobj. + +**Returns** + +The dictionary form of the QobjHeader. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjInstruction.md b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjInstruction.md new file mode 100644 index 00000000000..2bbca305490 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QasmQobjInstruction.md @@ -0,0 +1,73 @@ +--- +title: QasmQobjInstruction +description: API reference for qiskit.qobj.QasmQobjInstruction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QasmQobjInstruction +--- + +# QasmQobjInstruction + + + +`qiskit.qobj.QasmQobjInstruction(name, params=None, qubits=None, register=None, memory=None, condition=None, conditional=None, label=None, mask=None, relation=None, val=None, snapshot_type=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/qasm_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A class representing a single instruction in an QasmQobj Experiment. + +Instantiate a new QasmQobjInstruction object. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the instruction +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The list of parameters for the gate +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of `int` representing the qubits the instruction operates on +* **register** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – If a `measure` instruction this is a list of `int` containing the list of register slots in which to store the measurement results (must be the same length as qubits). If a `bfunc` instruction this is a single `int` of the register slot in which to store the result. +* **memory** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – If a `measure` instruction this is a list of `int` containing the list of memory slots to store the measurement results in (must be the same length as qubits). If a `bfunc` instruction this is a single `int` of the memory slot to store the boolean function result in. +* **condition** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – A tuple of the form `(int, int)` where the first `int` is the control register and the second `int` is the control value if the gate has a condition. +* **conditional** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The register index of the condition +* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional label assigned to the instruction +* **mask** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – For a `bfunc` instruction the hex value which is applied as an `AND` to the register bits. +* **relation** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Relational operator for comparing the masked register to the `val` kwarg. Can be either `==` (equals) or `!=` (not equals). +* **val** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Value to which to compare the masked register. In other words, the output of the function is `(register AND mask)` +* **snapshot\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – For snapshot instructions the type of snapshot to use + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QasmQobjInstruction object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the experiment config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[QasmQobjInstruction](#qiskit.qobj.QasmQobjInstruction "qiskit.qobj.QasmQobjInstruction") + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Instruction. + +**Returns** + +The dictionary form of the QasmQobjInstruction. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QobjExperimentHeader.md b/docs/api/qiskit/0.46/qiskit.qobj.QobjExperimentHeader.md new file mode 100644 index 00000000000..4d39794d8fe --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QobjExperimentHeader.md @@ -0,0 +1,62 @@ +--- +title: QobjExperimentHeader +description: API reference for qiskit.qobj.QobjExperimentHeader +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QobjExperimentHeader +--- + +# QobjExperimentHeader + + + +`qiskit.qobj.QobjExperimentHeader(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/common.py "view source code") + +Bases: [`QobjHeader`](qiskit.qobj.QobjHeader "qiskit.qobj.common.QobjHeader") + +A class representing a header dictionary for a Qobj Experiment. + +Instantiate a new Qobj dict field object. + +**Parameters** + +**kwargs** – arbitrary keyword arguments that can be accessed as attributes of the object. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QobjHeader object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the QobjHeader to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.QobjExperimentHeader.to_dict "qiskit.qobj.QobjExperimentHeader.to_dict"). + +**Returns** + +The QobjDictField from the input dictionary. + +**Return type** + +QobjDictFieldr + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the OpenQASM 2 Qobj. + +**Returns** + +The dictionary form of the QobjHeader. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QobjHeader.md b/docs/api/qiskit/0.46/qiskit.qobj.QobjHeader.md new file mode 100644 index 00000000000..f079518f430 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QobjHeader.md @@ -0,0 +1,62 @@ +--- +title: QobjHeader +description: API reference for qiskit.qobj.QobjHeader +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QobjHeader +--- + +# QobjHeader + + + +`qiskit.qobj.QobjHeader(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/common.py "view source code") + +Bases: `QobjDictField` + +A class used to represent a dictionary header in Qobj objects. + +Instantiate a new Qobj dict field object. + +**Parameters** + +**kwargs** – arbitrary keyword arguments that can be accessed as attributes of the object. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QobjHeader object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the QobjHeader to create. It will be in the same format as output by [`to_dict()`](#qiskit.qobj.QobjHeader.to_dict "qiskit.qobj.QobjHeader.to_dict"). + +**Returns** + +The QobjDictField from the input dictionary. + +**Return type** + +QobjDictFieldr + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the OpenQASM 2 Qobj. + +**Returns** + +The dictionary form of the QobjHeader. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.qobj.QobjMeasurementOption.md b/docs/api/qiskit/0.46/qiskit.qobj.QobjMeasurementOption.md new file mode 100644 index 00000000000..63deedcf568 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.qobj.QobjMeasurementOption.md @@ -0,0 +1,63 @@ +--- +title: QobjMeasurementOption +description: API reference for qiskit.qobj.QobjMeasurementOption +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.qobj.QobjMeasurementOption +--- + +# QobjMeasurementOption + + + +`qiskit.qobj.QobjMeasurementOption(name, params=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qobj/pulse_qobj.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +An individual measurement option. + +Instantiate a new QobjMeasurementOption object. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the measurement option +* **params** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The parameters of the measurement option. + +## Methods + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new QobjMeasurementOption object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary for the experiment config + +**Returns** + +The object from the input dictionary. + +**Return type** + +[QobjMeasurementOption](#qiskit.qobj.QobjMeasurementOption "qiskit.qobj.QobjMeasurementOption") + +### to\_dict + + + +`to_dict()` + +Return a dict format representation of the QobjMeasurementOption. + +**Returns** + +The dictionary form of the QasmMeasurementOption. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.CNOTDihedral.md b/docs/api/qiskit/0.46/qiskit.quantum_info.CNOTDihedral.md new file mode 100644 index 00000000000..bfbb10a5c39 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.CNOTDihedral.md @@ -0,0 +1,361 @@ +--- +title: CNOTDihedral +description: API reference for qiskit.quantum_info.CNOTDihedral +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.CNOTDihedral +--- + +# CNOTDihedral + + + +`qiskit.quantum_info.CNOTDihedral(data=None, num_qubits=None, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/dihedral/dihedral.py "view source code") + +Bases: `BaseOperator`, `AdjointMixin` + +An N-qubit operator from the CNOT-Dihedral group. + +> The CNOT-Dihedral group is generated by the quantum gates, [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"), [`TGate`](qiskit.circuit.library.TGate "qiskit.circuit.library.TGate"), and [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"). +> +> **Representation** +> +> An $N$-qubit CNOT-Dihedral operator is stored as an affine function and a phase polynomial, based on the convention in references \[1, 2]. +> +> The affine function consists of an $N \times N$ invertible binary matrix, and an $N$ binary vector. +> +> The phase polynomial is a polynomial of degree at most 3, in $N$ variables, whose coefficients are in the ring Z\_8 with 8 elements. +> +> ```python +> from qiskit import QuantumCircuit +> from qiskit.quantum_info import CNOTDihedral +> +> circ = QuantumCircuit(3) +> circ.cx(0, 1) +> circ.x(2) +> circ.t(1) +> circ.t(1) +> circ.t(1) +> elem = CNOTDihedral(circ) +> +> # Print the CNOTDihedral element +> print(elem) +> ``` + +```python +phase polynomial = +0 + 3*x_0 + 3*x_1 + 2*x_0*x_1 +affine function = + (x_0,x_0 + x_1,x_2 + 1) +``` + +**Circuit Conversion** + +> CNOTDihedral operators can be initialized from circuits containing *only* the following gates: [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate"), [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"), [`YGate`](qiskit.circuit.library.YGate "qiskit.circuit.library.YGate"), [`ZGate`](qiskit.circuit.library.ZGate "qiskit.circuit.library.ZGate"), [`TGate`](qiskit.circuit.library.TGate "qiskit.circuit.library.TGate"), [`TdgGate`](qiskit.circuit.library.TdgGate "qiskit.circuit.library.TdgGate") [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate"), [`SdgGate`](qiskit.circuit.library.SdgGate "qiskit.circuit.library.SdgGate"), [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"), [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate"), [`CSGate`](qiskit.circuit.library.CSGate "qiskit.circuit.library.CSGate"), [`CSdgGate`](qiskit.circuit.library.CSdgGate "qiskit.circuit.library.CSdgGate"), [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate"), [`CCZGate`](qiskit.circuit.library.CCZGate "qiskit.circuit.library.CCZGate"). They can be converted back into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object using the [`to_circuit()`](#qiskit.quantum_info.CNOTDihedral.to_circuit "qiskit.quantum_info.CNOTDihedral.to_circuit") or `to_instruction()` methods respectively. Note that this decomposition is not necessarily optimal in terms of number of gates if the number of qubits is more than two. +> +> CNOTDihedral operators can also be converted to [`Operator`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") objects using the [`to_operator()`](#qiskit.quantum_info.CNOTDihedral.to_operator "qiskit.quantum_info.CNOTDihedral.to_operator") method. This is done via decomposing to a circuit, and then simulating the circuit as a unitary operator. +> +> **References:** +> +> 1. Shelly Garion and Andrew W. Cross, *Synthesis of CNOT-Dihedral circuits with optimal number of two qubit gates*, [Quantum 4(369), 2020](https://quantum-journal.org/papers/q-2020-12-07-369/) +> 2. Andrew W. Cross, Easwar Magesan, Lev S. Bishop, John A. Smolin and Jay M. Gambetta, *Scalable randomised benchmarking of non-Clifford gates*, npj Quantum Inf 2, 16012 (2016). + +Initialize a CNOTDihedral operator object. + +**Parameters** + +* **data** ([*CNOTDihedral*](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – Optional, operator to initialize. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional, initialize an empty CNOTDihedral operator. +* **validate** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, validates the CNOTDihedral element. + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the type is invalid. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if validate=True and the CNOTDihedral element is invalid. + +## Attributes + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### name + +Unique string identifier for operation type. + + + +### num\_clbits + +Number of classical bits. + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the Operator. + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another CNOTDihedral. + +**Parameters** + +* **other** ([*CNOTDihedral*](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")) – a CNOTDihedral object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed CNOTDihedral. + +**Return type** + +[CNOTDihedral](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.CNOTDihedral.dot "qiskit.quantum_info.CNOTDihedral.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.CNOTDihedral.dot "qiskit.quantum_info.CNOTDihedral.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate of the CNOTDihedral. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another CNOTDihedral. + +**Parameters** + +**other** ([*CNOTDihedral*](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")) – a CNOTDihedral object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current CNOTDihedral, and $b$ is the other CNOTDihedral. + +**Return type** + +[CNOTDihedral](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the compose of a operator with itself n times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of times to compose with self (n>0). + +**Returns** + +the n-times composed operator. + +**Return type** + +[Clifford](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the operator are not equal, or the power is not a positive integer. + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another CNOTDihedral. + +**Parameters** + +**other** ([*CNOTDihedral*](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")) – a CNOTDihedral object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current CNOTDihedral, and $b$ is the other CNOTDihedral. + +**Return type** + +[CNOTDihedral](#qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_circuit + + + +`to_circuit()` + +Return a QuantumCircuit implementing the CNOT-Dihedral element. + +**Returns** + +a circuit implementation of the CNOTDihedral object. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**References** + +1. Shelly Garion and Andrew W. Cross, *Synthesis of CNOT-Dihedral circuits with optimal number of two qubit gates*, [Quantum 4(369), 2020](https://quantum-journal.org/papers/q-2020-12-07-369/) +2. Andrew W. Cross, Easwar Magesan, Lev S. Bishop, John A. Smolin and Jay M. Gambetta, *Scalable randomised benchmarking of non-Clifford gates*, npj Quantum Inf 2, 16012 (2016). + +### to\_instruction + + + +`to_instruction()` + +Return a Gate instruction implementing the CNOTDihedral object. + +### to\_matrix + + + +`to_matrix()` + +Convert operator to Numpy matrix. + +### to\_operator + + + +`to_operator()` + +Convert to an Operator object. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose of the CNOTDihedral. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Chi.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Chi.md new file mode 100644 index 00000000000..3a4e4f6885c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Chi.md @@ -0,0 +1,395 @@ +--- +title: Chi +description: API reference for qiskit.quantum_info.Chi +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Chi +--- + +# Chi + + + +`qiskit.quantum_info.Chi(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/channel/chi.py "view source code") + +Bases: `QuantumChannel` + +Pauli basis Chi-matrix representation of a quantum channel. + +The Chi-matrix representation of an $n$-qubit quantum channel $\mathcal{E}$ is a matrix $\chi$ such that the evolution of a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ is given by + +$$ +\mathcal{E}(ρ) = \frac{1}{2^n} \sum_{i, j} \chi_{i,j} P_i ρ P_j +$$ + +where $[P_0, P_1, ..., P_{4^{n}-1}]$ is the $n$-qubit Pauli basis in lexicographic order. It is related to the [`Choi`](qiskit.quantum_info.Choi "qiskit.quantum_info.Choi") representation by a change of basis of the Choi-matrix into the Pauli basis. The $\frac{1}{2^n}$ in the definition above is a normalization factor that arises from scaling the Pauli basis to make it orthonormal. + +See reference \[1] for further details. + +**References** + +1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015). [arXiv:1111.6950 \[quant-ph\]](https://arxiv.org/abs/1111.6950) + +Initialize a quantum channel Chi-matrix operator. + +**Parameters** + +* **or** (*data (*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Instruction or BaseOperator or matrix): data to initialize superoperator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input subsystem dimensions. \[Default: None] +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the output subsystem dimensions. \[Default: None] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit channel or cannot be initialized as a Chi-matrix. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. The Chi matrix representation is only valid for N-qubit channels. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return data. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint quantum channel. + + + This is equivalent to the matrix Hermitian conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the adjoint channel $\mathcal{{E}}^\dagger$ is $S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger$. + + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another Chi. + +**Parameters** + +* **other** ([*Chi*](#qiskit.quantum_info.Chi "qiskit.quantum_info.Chi")) – a Chi object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed Chi. + +**Return type** + +[Chi](#qiskit.quantum_info.Chi "qiskit.quantum_info.Chi") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.Chi.dot "qiskit.quantum_info.Chi.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Chi.dot "qiskit.quantum_info.Chi.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate quantum channel. + + + This is equivalent to the matrix complex conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the conjugate channel $\overline{{\mathcal{{E}}}}$ is $S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}$. + + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Chi. + +**Parameters** + +**other** ([*Chi*](#qiskit.quantum_info.Chi "qiskit.quantum_info.Chi")) – a Chi object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Chi, and $b$ is the other Chi. + +**Return type** + +[Chi](#qiskit.quantum_info.Chi "qiskit.quantum_info.Chi") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_cp + + + +`is_cp(atol=None, rtol=None)` + +Test if Choi-matrix is completely-positive (CP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_cptp + + + +`is_cptp(atol=None, rtol=None)` + +Return True if completely-positive trace-preserving (CPTP). + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_tp + + + +`is_tp(atol=None, rtol=None)` + +Test if a channel is trace-preserving (TP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if QuantumChannel is a unitary channel. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the quantum channel. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power exponent. + +**Returns** + +the channel $\mathcal{{E}} ^n$. + +**Return type** + +[SuperOp](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the SuperOp are not equal. + + + For non-positive or non-integer exponents the power is defined as the matrix power of the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{{E}}$, the SuperOp of the powered channel $\mathcal{{E}}^\n$ is $S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n$. + + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Chi. + +**Parameters** + +**other** ([*Chi*](#qiskit.quantum_info.Chi "qiskit.quantum_info.Chi")) – a Chi object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Chi, and $b$ is the other Chi. + +**Return type** + +[Chi](#qiskit.quantum_info.Chi "qiskit.quantum_info.Chi") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a Kraus or UnitaryGate circuit instruction. + +If the channel is unitary it will be added as a unitary gate, otherwise it will be added as a kraus simulator instruction. + +**Returns** + +A kraus instruction for the channel. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit CPTP quantum channel. + +### to\_operator + + + +`to_operator()` + +Try to convert channel to a unitary representation Operator. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose quantum channel. + + + This is equivalent to the matrix transpose in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation, ie. for a channel $\mathcal{E}$, the SuperOp of the transpose channel $\mathcal{{E}}^T$ is $S_{mathcal{E}^T} = S_{\mathcal{E}}^T$. + + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Choi.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Choi.md new file mode 100644 index 00000000000..4d23ae851bf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Choi.md @@ -0,0 +1,407 @@ +--- +title: Choi +description: API reference for qiskit.quantum_info.Choi +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Choi +--- + +# Choi + + + +`qiskit.quantum_info.Choi(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/channel/choi.py "view source code") + +Bases: `QuantumChannel` + +Choi-matrix representation of a Quantum Channel. + +The Choi-matrix representation of a quantum channel $\mathcal{E}$ is a matrix + +$$ +\Lambda = \sum_{i,j} |i\rangle\!\langle j|\otimes + \mathcal{E}\left(|i\rangle\!\langle j|\right) +$$ + +Evolution of a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ with respect to the Choi-matrix is given by + +$$ +\mathcal{E}(\rho) = \mbox{Tr}_{1}\left[\Lambda + (\rho^T \otimes \mathbb{I})\right] +$$ + +where $\mbox{Tr}_1$ is the [`partial_trace()`](quantum_info#qiskit.quantum_info.partial_trace "qiskit.quantum_info.partial_trace") over subsystem 1. + +See reference \[1] for further details. + +**References** + +1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015). [arXiv:1111.6950 \[quant-ph\]](https://arxiv.org/abs/1111.6950) + +Initialize a quantum channel Choi matrix operator. + +**Parameters** + +* **or** (*data (*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Instruction or BaseOperator or matrix): data to initialize superoperator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input subsystem dimensions. \[Default: None] +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the output subsystem dimensions. \[Default: None] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data cannot be initialized as a Choi matrix. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. If the input data is a Numpy array of shape (4\*\*N, 4\*\*N) qubit systems will be used. If the input operator is not an N-qubit operator, it will assign a single subsystem with dimension specified by the shape of the input. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return data. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint quantum channel. + + + This is equivalent to the matrix Hermitian conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the adjoint channel $\mathcal{{E}}^\dagger$ is $S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger$. + + +**Return type** + +*Self* + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another Choi. + +**Parameters** + +* **other** ([*Choi*](#qiskit.quantum_info.Choi "qiskit.quantum_info.Choi")) – a Choi object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed Choi. + +**Return type** + +[Choi](#qiskit.quantum_info.Choi "qiskit.quantum_info.Choi") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.Choi.dot "qiskit.quantum_info.Choi.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Choi.dot "qiskit.quantum_info.Choi.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate quantum channel. + + + This is equivalent to the matrix complex conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the conjugate channel $\overline{{\mathcal{{E}}}}$ is $S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}$. + + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Choi. + +**Parameters** + +**other** ([*Choi*](#qiskit.quantum_info.Choi "qiskit.quantum_info.Choi")) – a Choi object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Choi, and $b$ is the other Choi. + +**Return type** + +[Choi](#qiskit.quantum_info.Choi "qiskit.quantum_info.Choi") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_cp + + + +`is_cp(atol=None, rtol=None)` + +Test if Choi-matrix is completely-positive (CP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_cptp + + + +`is_cptp(atol=None, rtol=None)` + +Return True if completely-positive trace-preserving (CPTP). + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_tp + + + +`is_tp(atol=None, rtol=None)` + +Test if a channel is trace-preserving (TP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if QuantumChannel is a unitary channel. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the quantum channel. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power exponent. + +**Returns** + +the channel $\mathcal{{E}} ^n$. + +**Return type** + +[SuperOp](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the SuperOp are not equal. + + + For non-positive or non-integer exponents the power is defined as the matrix power of the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{{E}}$, the SuperOp of the powered channel $\mathcal{{E}}^\n$ is $S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n$. + + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Choi. + +**Parameters** + +**other** ([*Choi*](#qiskit.quantum_info.Choi "qiskit.quantum_info.Choi")) – a Choi object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Choi, and $b$ is the other Choi. + +**Return type** + +[Choi](#qiskit.quantum_info.Choi "qiskit.quantum_info.Choi") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a Kraus or UnitaryGate circuit instruction. + +If the channel is unitary it will be added as a unitary gate, otherwise it will be added as a kraus simulator instruction. + +**Returns** + +A kraus instruction for the channel. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit CPTP quantum channel. + +### to\_operator + + + +`to_operator()` + +Try to convert channel to a unitary representation Operator. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose quantum channel. + + + This is equivalent to the matrix transpose in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation, ie. for a channel $\mathcal{E}$, the SuperOp of the transpose channel $\mathcal{{E}}^T$ is $S_{mathcal{E}^T} = S_{\mathcal{E}}^T$. + + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Clifford.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Clifford.md new file mode 100644 index 00000000000..352b6a551b9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Clifford.md @@ -0,0 +1,661 @@ +--- +title: Clifford +description: API reference for qiskit.quantum_info.Clifford +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Clifford +--- + +# Clifford + + + +`qiskit.quantum_info.Clifford(data, validate=True, copy=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/clifford.py "view source code") + +Bases: `BaseOperator`, `AdjointMixin`, [`Operation`](qiskit.circuit.Operation "qiskit.circuit.operation.Operation") + +An N-qubit unitary operator from the Clifford group. + +**Representation** + +An *N*-qubit Clifford operator is stored as a length *2N × (2N+1)* boolean tableau using the convention from reference \[1]. + +* Rows 0 to *N-1* are the *destabilizer* group generators +* Rows *N* to *2N-1* are the *stabilizer* group generators. + +The internal boolean tableau for the Clifford can be accessed using the `tableau` attribute. The destabilizer or stabilizer rows can each be accessed as a length-N Stabilizer table using [`destab`](#qiskit.quantum_info.Clifford.destab "qiskit.quantum_info.Clifford.destab") and [`stab`](#qiskit.quantum_info.Clifford.stab "qiskit.quantum_info.Clifford.stab") attributes. + +A more easily human readable representation of the Clifford operator can be obtained by calling the [`to_dict()`](#qiskit.quantum_info.Clifford.to_dict "qiskit.quantum_info.Clifford.to_dict") method. This representation is also used if a Clifford object is printed as in the following example + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import Clifford + +# Bell state generation circuit +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) +cliff = Clifford(qc) + +# Print the Clifford +print(cliff) + +# Print the Clifford destabilizer rows +print(cliff.to_labels(mode="D")) + +# Print the Clifford stabilizer rows +print(cliff.to_labels(mode="S")) +``` + +```python +Clifford: Stabilizer = ['+XX', '+ZZ'], Destabilizer = ['+IZ', '+XI'] +['+IZ', '+XI'] +['+XX', '+ZZ'] +``` + +**Circuit Conversion** + +Clifford operators can be initialized from circuits containing *only* the following Clifford gates: [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate"), [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate"), [`YGate`](qiskit.circuit.library.YGate "qiskit.circuit.library.YGate"), [`ZGate`](qiskit.circuit.library.ZGate "qiskit.circuit.library.ZGate"), [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate"), [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate"), [`SdgGate`](qiskit.circuit.library.SdgGate "qiskit.circuit.library.SdgGate"), [`SXGate`](qiskit.circuit.library.SXGate "qiskit.circuit.library.SXGate"), [`SXdgGate`](qiskit.circuit.library.SXdgGate "qiskit.circuit.library.SXdgGate"), [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"), [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate"), [`CYGate`](qiskit.circuit.library.CYGate "qiskit.circuit.library.CYGate"), `DXGate`, [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate"), [`iSwapGate`](qiskit.circuit.library.iSwapGate "qiskit.circuit.library.iSwapGate"), [`ECRGate`](qiskit.circuit.library.ECRGate "qiskit.circuit.library.ECRGate"), [`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction"), [`PermutationGate`](qiskit.circuit.library.PermutationGate "qiskit.circuit.library.PermutationGate"). They can be converted back into a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object using the [`to_circuit()`](#qiskit.quantum_info.Clifford.to_circuit "qiskit.quantum_info.Clifford.to_circuit") or [`to_instruction()`](#qiskit.quantum_info.Clifford.to_instruction "qiskit.quantum_info.Clifford.to_instruction") methods respectively. Note that this decomposition is not necessarily optimal in terms of number of gates. + + + A minimally generating set of gates for Clifford circuits is the [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate") and [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate") gate and *either* the [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") or [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate") two-qubit gate. + + +Clifford operators can also be converted to [`Operator`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") objects using the [`to_operator()`](#qiskit.quantum_info.Clifford.to_operator "qiskit.quantum_info.Clifford.to_operator") method. This is done via decomposing to a circuit, and then simulating the circuit as a unitary operator. + +**References** + +1. S. Aaronson, D. Gottesman, *Improved Simulation of Stabilizer Circuits*, Phys. Rev. A 70, 052328 (2004). [arXiv:quant-ph/0406196](https://arxiv.org/abs/quant-ph/0406196) + +Initialize an operator object. + +## Attributes + + + +### destab + +The destabilizer array for the symplectic representation. + + + +### destab\_phase + +Return phase of destabilizer with boolean representation. + + + +### destab\_x + +The destabilizer x array for the symplectic representation. + + + +### destab\_z + +The destabilizer z array for the symplectic representation. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### name + +Unique string identifier for operation type. + + + +### num\_clbits + +Number of classical bits. + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### phase + +Return phase with boolean representation. + + + +### qargs + +Return the qargs for the operator. + + + +### stab + +The stabilizer array for the symplectic representation. + + + +### stab\_phase + +Return phase of stabilizer with boolean representation. + + + +### stab\_x + +The stabilizer x array for the symplectic representation. + + + +### stab\_z + +The stabilizer array for the symplectic representation. + + + +### symplectic\_matrix + +Return boolean symplectic matrix. + + + +### x + +The x array for the symplectic representation. + + + +### z + +The z array for the symplectic representation. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the Operator. + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another Clifford. + +**Parameters** + +* **other** ([*Clifford*](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a Clifford object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed Clifford. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.Clifford.dot "qiskit.quantum_info.Clifford.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Clifford.dot "qiskit.quantum_info.Clifford.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate of the Clifford. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Clifford. + +**Parameters** + +**other** ([*Clifford*](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a Clifford object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Clifford, and $b$ is the other Clifford. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +### from\_circuit + + + +`static from_circuit(circuit)` + +Initialize from a QuantumCircuit or Instruction. + +**Parameters** + +**circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – instruction to initialize. + +**Returns** + +the Clifford object for the instruction. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input instruction is non-Clifford or contains classical register instruction. + +### from\_dict + + + +`classmethod from_dict(obj)` + +Load a Clifford from a dictionary + +### from\_label + + + +`static from_label(label)` + +Return a tensor product of single-qubit Clifford gates. + +**Parameters** + +**label** (*string*) – single-qubit operator string. + +**Returns** + +The N-qubit Clifford operator. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the label contains invalid characters. + +**Additional Information:** + +The labels correspond to the single-qubit Cliffords are + +* * Label + * Stabilizer + * Destabilizer +* * `"I"` + * +Z + * +X +* * `"X"` + * -Z + * +X +* * `"Y"` + * -Z + * -X +* * `"Z"` + * +Z + * -X +* * `"H"` + * +X + * +Z +* * `"S"` + * +Z + * +Y + +### from\_linear\_function + + + +`classmethod from_linear_function(linear_function)` + +Create a Clifford from a Linear Function. + +If the linear function is represented by a nxn binary invertible matrix A, then the corresponding Clifford has symplectic matrix \[\[A^t, 0], \[0, A^\{-1}]]. + +**Parameters** + +**linear\_function** ([*LinearFunction*](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction")) – A linear function to be converted. + +**Returns** + +the Clifford object for this linear function. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +### from\_matrix + + + +`classmethod from_matrix(matrix)` + +Create a Clifford from a unitary matrix. + +Note that this function takes exponentially long time w\.r.t. the number of qubits. + +**Parameters** + +**matrix** (*np.array*) – A unitary matrix representing a Clifford to be converted. + +**Returns** + +the Clifford object for the unitary matrix. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input is not a Clifford matrix. + +### from\_operator + + + +`classmethod from_operator(operator)` + +Create a Clifford from a operator. + +Note that this function takes exponentially long time w\.r.t. the number of qubits. + +**Parameters** + +**operator** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – An operator representing a Clifford to be converted. + +**Returns** + +the Clifford object for the operator. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input is not a Clifford operator. + +### from\_permutation + + + +`classmethod from_permutation(permutation_gate)` + +Create a Clifford from a PermutationGate. + +**Parameters** + +**permutation\_gate** ([*PermutationGate*](qiskit.circuit.library.PermutationGate "qiskit.circuit.library.PermutationGate")) – A permutation to be converted. + +**Returns** + +the Clifford object for this permutation. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_unitary + + + +`is_unitary()` + +Return True if the Clifford table is valid. + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the compose of a operator with itself n times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of times to compose with self (n>0). + +**Returns** + +the n-times composed operator. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the operator are not equal, or the power is not a positive integer. + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Clifford. + +**Parameters** + +**other** ([*Clifford*](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a Clifford object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Clifford, and $b$ is the other Clifford. + +**Return type** + +[Clifford](#qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_circuit + + + +`to_circuit()` + +Return a QuantumCircuit implementing the Clifford. + +For N \<= 3 qubits this is based on optimal CX cost decomposition from reference \[1]. For N > 3 qubits this is done using the general non-optimal compilation routine from reference \[2]. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**References** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) +2. S. Aaronson, D. Gottesman, *Improved Simulation of Stabilizer Circuits*, Phys. Rev. A 70, 052328 (2004). [arXiv:quant-ph/0406196](https://arxiv.org/abs/quant-ph/0406196) + +### to\_dict + + + +`to_dict()` + +Return dictionary representation of Clifford object. + +### to\_instruction + + + +`to_instruction()` + +Return a Gate instruction implementing the Clifford. + +### to\_labels + + + +`to_labels(array=False, mode='B')` + +Convert a Clifford to a list Pauli (de)stabilizer string labels. + +For large Clifford converting using the `array=True` kwarg will be more efficient since it allocates memory for the full Numpy array of labels in advance. + +| Label | Phase | Symplectic | Matrix | Pauli | +| ------ | ----- | ---------- | ------------------------------------------------ | ----- | +| `"+I"` | 0 | $[0, 0]$ | $\begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}$ | $I$ | +| `"-I"` | 1 | $[0, 0]$ | $\begin{bmatrix} -1 & 0 \\ 0 & -1 \end{bmatrix}$ | $-I$ | +| `"X"` | 0 | $[1, 0]$ | $\begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix}$ | $X$ | +| `"-X"` | 1 | $[1, 0]$ | $\begin{bmatrix} 0 & -1 \\ -1 & 0 \end{bmatrix}$ | $-X$ | +| `"Y"` | 0 | $[1, 1]$ | $\begin{bmatrix} 0 & 1 \\ -1 & 0 \end{bmatrix}$ | $iY$ | +| `"-Y"` | 1 | $[1, 1]$ | $\begin{bmatrix} 0 & -1 \\ 1 & 0 \end{bmatrix}$ | $-iY$ | +| `"Z"` | 0 | $[0, 1]$ | $\begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}$ | $Z$ | +| `"-Z"` | 1 | $[0, 1]$ | $\begin{bmatrix} -1 & 0 \\ 0 & 1 \end{bmatrix}$ | $-Z$ | + +**Parameters** + +* **array** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – return a Numpy array if True, otherwise return a list (Default: False). +* **mode** (*Literal\["S", "D", "B"]*) – return both stabilizer and destabilizer if “B”, return only stabilizer if “S” and return only destabilizer if “D”. + +**Returns** + +The rows of the StabilizerTable in label form. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") or array + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if stabilizer and destabilizer are both False. + +### to\_matrix + + + +`to_matrix()` + +Convert operator to Numpy matrix. + +### to\_operator + + + +`to_operator()` + +Convert to an Operator object. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose of the Clifford. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.DensityMatrix.md b/docs/api/qiskit/0.46/qiskit.quantum_info.DensityMatrix.md new file mode 100644 index 00000000000..7803a2dea97 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.DensityMatrix.md @@ -0,0 +1,703 @@ +--- +title: DensityMatrix +description: API reference for qiskit.quantum_info.DensityMatrix +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.DensityMatrix +--- + +# DensityMatrix + + + +`qiskit.quantum_info.DensityMatrix(data, dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/densitymatrix.py "view source code") + +Bases: `QuantumState`, `TolerancesMixin` + +DensityMatrix class + +Initialize a density matrix object. + +**Parameters** + +* **or** (*data (np.ndarray or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or matrix\_like or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – qiskit.circuit.Instruction): A statevector, quantum instruction or an object with a `to_operator` or `to_matrix` method from which the density matrix can be constructed. If a vector the density matrix is constructed as the projector of that vector. If a quantum instruction, the density matrix is constructed by assuming all qubits are initialized in the zero state. +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Optional. The subsystem dimension of the state (See additional information). + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not valid. + +**Additional Information:** + +The `dims` kwarg can be None, an integer, or an iterable of integers. + +* `Iterable` – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list. +* `Int` or `None` – the leading dimension of the input matrix specifies the total dimension of the density matrix. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return data. + + + +### dim + +Return total state dimension. + + + +### num\_qubits + +Return the number of qubits if a N-qubit state or None otherwise. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### conjugate + + + +`conjugate()` + +Return the conjugate of the density matrix. + +### copy + + + +`copy()` + +Make a copy of current operator. + +### dims + + + +`dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### draw + + + +`draw(output=None, **drawer_args)` + +Return a visualization of the Statevector. + +**repr**: ASCII TextMatrix of the state’s `__repr__`. + +**text**: ASCII TextMatrix that can be printed in the console. + +**latex**: An IPython Latex object for displaying in Jupyter Notebooks. + +**latex\_source**: Raw, uncompiled ASCII source to generate array using LaTeX. + +**qsphere**: Matplotlib figure, rendering of density matrix using plot\_state\_qsphere(). + +**hinton**: Matplotlib figure, rendering of density matrix using plot\_state\_hinton(). + +**bloch**: Matplotlib figure, rendering of density matrix using plot\_bloch\_multivector(). + +**Parameters** + +* **output** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Select the output method to use for drawing the state. Valid choices are repr, text, latex, latex\_source, qsphere, hinton, or bloch. Default is repr. Default can be changed by adding the line `state_drawer = ` to `~/.qiskit/settings.conf` under `[default]`. +* **drawer\_args** – Arguments to be passed directly to the relevant drawing function or constructor (TextMatrix(), array\_to\_latex(), plot\_state\_qsphere(), plot\_state\_hinton() or plot\_bloch\_multivector()). See the relevant function under qiskit.visualization for that function’s documentation. + +**Returns** + +`matplotlib.Figure` or [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") or `TextMatrix` or `IPython.display.Latex`: Drawing of the Statevector. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – when an invalid output method is selected. + +### evolve + + + +`evolve(other, qargs=None)` + +Evolve a quantum state by an operator. + +**Parameters** + +* **QuantumChannel** (*other (Operator or*) – or Instruction or Circuit): The operator to evolve by. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list of QuantumState subsystem positions to apply the operator on. + +**Returns** + +the output density matrix. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the operator dimension does not match the specified QuantumState subsystem dimensions. + +### expand + + + +`expand(other)` + +Return the tensor product state other ⊗ self. + +**Parameters** + +**other** ([*DensityMatrix*](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a quantum state object. + +**Returns** + +the tensor product state other ⊗ self. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state. + +### expectation\_value + + + +`expectation_value(oper, qargs=None)` + +Compute the expectation value of an operator. + +**Parameters** + +* **oper** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator to evaluate expval. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to apply the operator on. + +**Returns** + +the expectation value. + +**Return type** + +[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### from\_instruction + + + +`classmethod from_instruction(instruction)` + +Return the output density matrix of an instruction. + +The statevector is initialized in the state $|{0,\ldots,0}\rangle$ of the same number of qubits as the input instruction or circuit, evolved by the input instruction, and the output statevector returned. + +**Parameters** + +**instruction** ([*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – instruction or circuit + +**Returns** + +the final density matrix. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instruction contains invalid instructions for density matrix simulation. + +### from\_int + + + +`static from_int(i, dims)` + +Return a computational basis state density matrix. + +**Parameters** + +* **i** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the basis state element. +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The subsystem dimensions of the statevector (See additional information). + +**Returns** + +The computational basis state $|i\rangle\!\langle i|$. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Additional Information:** + +The `dims` kwarg can be an integer or an iterable of integers. + +* `Iterable` – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list. +* `Int` – the integer specifies the total dimension of the state. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem. + +### from\_label + + + +`classmethod from_label(label)` + +Return a tensor product of Pauli X,Y,Z eigenstates. + +| Label | Statevector | +| ----- | ----------------------------------------------------------- | +| `"0"` | $\begin{pmatrix} 1 & 0 \\ 0 & 0 \end{pmatrix}$ | +| `"1"` | $\begin{pmatrix} 0 & 0 \\ 0 & 1 \end{pmatrix}$ | +| `"+"` | $\frac{1}{2}\begin{pmatrix} 1 & 1 \\ 1 & 1 \end{pmatrix}$ | +| `"-"` | $\frac{1}{2}\begin{pmatrix} 1 & -1 \\ -1 & 1 \end{pmatrix}$ | +| `"r"` | $\frac{1}{2}\begin{pmatrix} 1 & -i \\ i & 1 \end{pmatrix}$ | +| `"l"` | $\frac{1}{2}\begin{pmatrix} 1 & i \\ -i & 1 \end{pmatrix}$ | + +**Parameters** + +**label** (*string*) – a eigenstate string ket label (see table for allowed values). + +**Returns** + +The N-qubit basis state density matrix. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the label contains invalid characters, or the length of the label is larger than an explicitly specified num\_qubits. + +### is\_valid + + + +`is_valid(atol=None, rtol=None)` + +Return True if trace 1 and positive semidefinite. + +### measure + + + +`measure(qargs=None)` + +Measure subsystems and return outcome and post-measure state. + +Note that this function uses the QuantumStates internal random number generator for sampling the measurement outcome. The RNG seed can be set using the [`seed()`](#qiskit.quantum_info.DensityMatrix.seed "qiskit.quantum_info.DensityMatrix.seed") method. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +**the pair `(outcome, state)` where `outcome` is the** + +measurement outcome string label, and `state` is the collapsed post-measurement state for the corresponding outcome. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### partial\_transpose + + + +`partial_transpose(qargs)` + +Return partially transposed density matrix. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The subsystems to be transposed. + +**Returns** + +The partially transposed density matrix. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +### probabilities + + + +`probabilities(qargs=None, decimals=None)` + +Return the subsystem measurement probability vector. + +Measurement probabilities are with respect to measurement in the computation (diagonal) basis. + +**Parameters** + +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None). +* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +The Numpy vector array of probabilities. + +**Return type** + +np.array + +**Examples** + +Consider a 2-qubit product state $\rho=\rho_1\otimes\rho_0$ with $\rho_1=|+\rangle\!\langle+|$, $\rho_0=|0\rangle\!\langle0|$. + +```python +from qiskit.quantum_info import DensityMatrix + +rho = DensityMatrix.from_label('+0') + +# Probabilities for measuring both qubits +probs = rho.probabilities() +print('probs: {}'.format(probs)) + +# Probabilities for measuring only qubit-0 +probs_qubit_0 = rho.probabilities([0]) +print('Qubit-0 probs: {}'.format(probs_qubit_0)) + +# Probabilities for measuring only qubit-1 +probs_qubit_1 = rho.probabilities([1]) +print('Qubit-1 probs: {}'.format(probs_qubit_1)) +``` + +```python +probs: [0.5 0. 0.5 0. ] +Qubit-0 probs: [1. 0.] +Qubit-1 probs: [0.5 0.5] +``` + +We can also permute the order of qubits in the `qargs` list to change the qubit position in the probabilities output + +```python +from qiskit.quantum_info import DensityMatrix + +rho = DensityMatrix.from_label('+0') + +# Probabilities for measuring both qubits +probs = rho.probabilities([0, 1]) +print('probs: {}'.format(probs)) + +# Probabilities for measuring both qubits +# but swapping qubits 0 and 1 in output +probs_swapped = rho.probabilities([1, 0]) +print('Swapped probs: {}'.format(probs_swapped)) +``` + +```python +probs: [0.5 0. 0.5 0. ] +Swapped probs: [0.5 0.5 0. 0. ] +``` + +### probabilities\_dict + + + +`probabilities_dict(qargs=None, decimals=None)` + +Return the subsystem measurement probability dictionary. + +Measurement probabilities are with respect to measurement in the computation (diagonal) basis. + +This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished. + +**Parameters** + +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None). +* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +The measurement probabilities in dict (ket) form. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### purity + + + +`purity()` + +Return the purity of the quantum state. + +### reset + + + +`reset(qargs=None)` + +Reset state or subsystems to the 0-state. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None). + +**Returns** + +the reset state. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Additional Information:** + +If all subsystems are reset this will return the ground state on all subsystems. If only a some subsystems are reset this function will perform evolution by the reset [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") of the reset subsystems. + +### reverse\_qargs + + + +`reverse_qargs()` + +Return a DensityMatrix with reversed subsystem ordering. + +For a tensor product state this is equivalent to reversing the order of tensor product subsystems. For a density matrix $\rho = \rho_{n-1} \otimes ... \otimes \rho_0$ the returned state will be $\rho_0 \otimes ... \otimes \rho_{n-1}$. + +**Returns** + +the state with reversed subsystem order. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +### sample\_counts + + + +`sample_counts(shots, qargs=None)` + +Sample a dict of qubit measurement outcomes in the computational basis. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of samples to generate. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +sampled counts dictionary. + +**Return type** + +[Counts](qiskit.result.Counts "qiskit.result.Counts") + +Additional Information: + +> This function *samples* measurement outcomes using the measure [`probabilities()`](#qiskit.quantum_info.DensityMatrix.probabilities "qiskit.quantum_info.DensityMatrix.probabilities") for the current state and qargs. It does not actually implement the measurement so the current state is not modified. +> +> The seed for random number generator used for sampling can be set to a fixed value by using the stats [`seed()`](#qiskit.quantum_info.DensityMatrix.seed "qiskit.quantum_info.DensityMatrix.seed") method. + +### sample\_memory + + + +`sample_memory(shots, qargs=None)` + +Sample a list of qubit measurement outcomes in the computational basis. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of samples to generate. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +list of sampled counts if the order sampled. + +**Return type** + +np.array + +Additional Information: + +> This function *samples* measurement outcomes using the measure [`probabilities()`](#qiskit.quantum_info.DensityMatrix.probabilities "qiskit.quantum_info.DensityMatrix.probabilities") for the current state and qargs. It does not actually implement the measurement so the current state is not modified. +> +> The seed for random number generator used for sampling can be set to a fixed value by using the stats [`seed()`](#qiskit.quantum_info.DensityMatrix.seed "qiskit.quantum_info.DensityMatrix.seed") method. + +### seed + + + +`seed(value=None)` + +Set the seed for the quantum state RNG. + +### tensor + + + +`tensor(other)` + +Return the tensor product state self ⊗ other. + +**Parameters** + +**other** ([*DensityMatrix*](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a quantum state object. + +**Returns** + +the tensor product operator self ⊗ other. + +**Return type** + +[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state. + +### to\_dict + + + +`to_dict(decimals=None)` + +Convert the density matrix to dictionary form. + +This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished. + +**Parameters** + +**decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +the dictionary form of the DensityMatrix. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Examples** + +The ket-form of a 2-qubit density matrix $rho = |-\rangle\!\langle -|\otimes |0\rangle\!\langle 0|$ + +```python +from qiskit.quantum_info import DensityMatrix + +rho = DensityMatrix.from_label('-0') +print(rho.to_dict()) +``` + +```python +{ + '00|00': (0.4999999999999999+0j), + '10|00': (-0.4999999999999999-0j), + '00|10': (-0.4999999999999999+0j), + '10|10': (0.4999999999999999+0j) +} +``` + +For non-qubit subsystems the integer range can go from 0 to 9. For example in a qutrit system + +```python +import numpy as np +from qiskit.quantum_info import DensityMatrix + +mat = np.zeros((9, 9)) +mat[0, 0] = 0.25 +mat[3, 3] = 0.25 +mat[6, 6] = 0.25 +mat[-1, -1] = 0.25 +rho = DensityMatrix(mat, dims=(3, 3)) +print(rho.to_dict()) +``` + +```python +{'00|00': (0.25+0j), '10|10': (0.25+0j), '20|20': (0.25+0j), '22|22': (0.25+0j)} +``` + +For large subsystem dimensions delimiters are required. The following example is for a 20-dimensional system consisting of a qubit and 10-dimensional qudit. + +```python +import numpy as np +from qiskit.quantum_info import DensityMatrix + +mat = np.zeros((2 * 10, 2 * 10)) +mat[0, 0] = 0.5 +mat[-1, -1] = 0.5 +rho = DensityMatrix(mat, dims=(2, 10)) +print(rho.to_dict()) +``` + +```python +{'00|00': (0.5+0j), '91|91': (0.5+0j)} +``` + +### to\_operator + + + +`to_operator()` + +Convert to Operator + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### to\_statevector + + + +`to_statevector(atol=None, rtol=None)` + +Return a statevector from a pure density matrix. + +**Parameters** + +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Absolute tolerance for checking operation validity. +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Relative tolerance for checking operation validity. + +**Returns** + +**The pure density matrix’s corresponding statevector.** + +Corresponds to the eigenvector of the only non-zero eigenvalue. + +**Return type** + +[Statevector](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the state is not pure. + +### trace + + + +`trace()` + +Return the trace of the density matrix. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Kraus.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Kraus.md new file mode 100644 index 00000000000..3d9a6349de7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Kraus.md @@ -0,0 +1,395 @@ +--- +title: Kraus +description: API reference for qiskit.quantum_info.Kraus +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Kraus +--- + +# Kraus + + + +`qiskit.quantum_info.Kraus(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/channel/kraus.py "view source code") + +Bases: `QuantumChannel` + +Kraus representation of a quantum channel. + +For a quantum channel $\mathcal{E}$, the Kraus representation is given by a set of matrices $[A_0,...,A_{K-1}]$ such that the evolution of a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ is given by + +$$ +\mathcal{E}(\rho) = \sum_{i=0}^{K-1} A_i \rho A_i^\dagger +$$ + +A general operator map $\mathcal{G}$ can also be written using the generalized Kraus representation which is given by two sets of matrices $[A_0,...,A_{K-1}]$, $[B_0,...,A_{B-1}]$ such that + +$$ +\mathcal{G}(\rho) = \sum_{i=0}^{K-1} A_i \rho B_i^\dagger +$$ + +See reference \[1] for further details. + +**References** + +1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015). [arXiv:1111.6950 \[quant-ph\]](https://arxiv.org/abs/1111.6950) + +Initialize a quantum channel Kraus operator. + +**Parameters** + +* **data** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*circuit.instruction.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction") *| BaseOperator | np.ndarray*) – data to initialize superoperator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *| None*) – the input subsystem dimensions. +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *| None*) – the output subsystem dimensions. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data cannot be initialized as a list of Kraus matrices. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. If the input data is a list of Numpy arrays of shape $(2^N,\,2^N)$ qubit systems will be used. If the input does not correspond to an N-qubit channel, it will assign a single subsystem with dimension specified by the shape of the input. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return list of Kraus matrices for channel. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint quantum channel. + + + This is equivalent to the matrix Hermitian conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the adjoint channel $\mathcal{{E}}^\dagger$ is $S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger$. + + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another Kraus. + +**Parameters** + +* **other** ([*Kraus*](#qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus")) – a Kraus object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed Kraus. + +**Return type** + +[Kraus](#qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.Kraus.dot "qiskit.quantum_info.Kraus.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Kraus.dot "qiskit.quantum_info.Kraus.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate quantum channel. + + + This is equivalent to the matrix complex conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the conjugate channel $\overline{{\mathcal{{E}}}}$ is $S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}$. + + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Kraus. + +**Parameters** + +**other** ([*Kraus*](#qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus")) – a Kraus object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Kraus, and $b$ is the other Kraus. + +**Return type** + +[Kraus](#qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_cp + + + +`is_cp(atol=None, rtol=None)` + +Test if Choi-matrix is completely-positive (CP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_cptp + + + +`is_cptp(atol=None, rtol=None)` + +Return True if completely-positive trace-preserving. + +### is\_tp + + + +`is_tp(atol=None, rtol=None)` + +Test if a channel is trace-preserving (TP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if QuantumChannel is a unitary channel. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the quantum channel. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power exponent. + +**Returns** + +the channel $\mathcal{{E}} ^n$. + +**Return type** + +[SuperOp](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the SuperOp are not equal. + + + For non-positive or non-integer exponents the power is defined as the matrix power of the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{{E}}$, the SuperOp of the powered channel $\mathcal{{E}}^\n$ is $S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n$. + + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Kraus. + +**Parameters** + +**other** ([*Kraus*](#qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus")) – a Kraus object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Kraus, and $b$ is the other Kraus. + +**Return type** + +[Kraus](#qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a Kraus or UnitaryGate circuit instruction. + +If the channel is unitary it will be added as a unitary gate, otherwise it will be added as a kraus simulator instruction. + +**Returns** + +A kraus instruction for the channel. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit CPTP quantum channel. + +### to\_operator + + + +`to_operator()` + +Try to convert channel to a unitary representation Operator. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose quantum channel. + + + This is equivalent to the matrix transpose in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation, ie. for a channel $\mathcal{E}$, the SuperOp of the transpose channel $\mathcal{{E}}^T$ is $S_{mathcal{E}^T} = S_{\mathcal{E}}^T$. + + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Operator.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Operator.md new file mode 100644 index 00000000000..fe2ac5fcdff --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Operator.md @@ -0,0 +1,488 @@ +--- +title: Operator +description: API reference for qiskit.quantum_info.Operator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Operator +--- + +# Operator + + + +`qiskit.quantum_info.Operator(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/operator.py "view source code") + +Bases: `LinearOp` + +Matrix operator class + +This represents a matrix operator $M$ that will [`evolve()`](qiskit.quantum_info.Statevector#evolve "qiskit.quantum_info.Statevector.evolve") a [`Statevector`](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") $|\psi\rangle$ by matrix-vector multiplication + +$$ +|\psi\rangle \mapsto M|\psi\rangle, +$$ + +and will [`evolve()`](qiskit.quantum_info.DensityMatrix#evolve "qiskit.quantum_info.DensityMatrix.evolve") a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ by left and right multiplication + +$$ +\rho \mapsto M \rho M^\dagger. +$$ + +Initialize an operator object. + +**Parameters** + +* **data** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation") *or BaseOperator or matrix*) – data to initialize operator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input subsystem dimensions. \[Default: None] +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the output subsystem dimensions. \[Default: None] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data cannot be initialized as an operator. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. If the input data is a Numpy array of shape (2\*\*N, 2\*\*N) qubit systems will be used. If the input operator is not an N-qubit operator, it will assign a single subsystem with dimension specified by the shape of the input. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +The underlying Numpy array. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return operator settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the Operator. + +**Return type** + +*Self* + +### apply\_permutation + + + +`apply_permutation(perm, front=False)` + +Modifies operator’s data by composing it with a permutation. + +**Parameters** + +* **perm** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – permutation pattern, describing which qubits occupy the positions 0, 1, 2, etc. after applying the permutation. +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set to `True` the permutation is applied before the operator, when set to `False` the permutation is applied after the operator. + +**Returns** + +The modified operator. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the size of the permutation pattern does not match the dimensions of the operator. + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another Operator. + +**Parameters** + +* **other** ([*Operator*](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – a Operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed Operator. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.Operator.dot "qiskit.quantum_info.Operator.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Operator.dot "qiskit.quantum_info.Operator.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate of the Operator. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### draw + + + +`draw(output=None, **drawer_args)` + +Return a visualization of the Operator. + +**repr**: String of the state’s `__repr__`. + +**text**: ASCII TextMatrix that can be printed in the console. + +**latex**: An IPython Latex object for displaying in Jupyter Notebooks. + +**latex\_source**: Raw, uncompiled ASCII source to generate array using LaTeX. + +**Parameters** + +* **output** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Select the output method to use for drawing the state. Valid choices are repr, text, latex, latex\_source, Default is repr. +* **drawer\_args** – Arguments to be passed directly to the relevant drawing function or constructor (TextMatrix(), array\_to\_latex()). See the relevant function under qiskit.visualization for that function’s documentation. + +**Returns** + +Drawing of the Operator. + +**Return type** + +[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") or `TextMatrix` or `IPython.display.Latex` + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – when an invalid output method is selected. + +### equiv + + + +`equiv(other, rtol=None, atol=None)` + +Return True if operators are equivalent up to global phase. + +**Parameters** + +* **other** ([*Operator*](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – relative tolerance value for comparison. +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – absolute tolerance value for comparison. + +**Returns** + +True if operators are equivalent up to global phase. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Operator. + +**Parameters** + +**other** ([*Operator*](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – a Operator object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Operator, and $b$ is the other Operator. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +### from\_circuit + + + +`classmethod from_circuit(circuit, ignore_set_layout=False, layout=None, final_layout=None)` + +Create a new Operator object from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +While a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object can passed directly as `data` to the class constructor this provides no options on how the circuit is used to create an [`Operator`](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator"). This constructor method lets you control how the [`Operator`](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") is created so it can be adjusted for a particular use case. + +By default this constructor method will permute the qubits based on a configured initial layout (i.e. after it was transpiled). It also provides an option to manually provide a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object directly. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") to create an Operator object from. +* **ignore\_set\_layout** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – When set to `True` if the input `circuit` has a layout set it will be ignored +* **layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – If specified this kwarg can be used to specify a particular layout to use to permute the qubits in the created [`Operator`](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator"). If this is specified it will be used instead of a layout contained in the `circuit` input. If specified the virtual bits in the [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") must be present in the `circuit` input. +* **final\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – If specified this kwarg can be used to represent the output permutation caused by swap insertions during the routing stage of the transpiler. + +**Returns** + +An operator representing the input circuit + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +### from\_label + + + +`classmethod from_label(label)` + +Return a tensor product of single-qubit operators. + +**Parameters** + +**label** (*string*) – single-qubit operator string. + +**Returns** + +The N-qubit operator. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the label contains invalid characters, or the length of the label is larger than an explicitly specified num\_qubits. + +**Additional Information:** + +The labels correspond to the single-qubit matrices: ‘I’: \[\[1, 0], \[0, 1]] ‘X’: \[\[0, 1], \[1, 0]] ‘Y’: \[\[0, -1j], \[1j, 0]] ‘Z’: \[\[1, 0], \[0, -1]] ‘H’: \[\[1, 1], \[1, -1]] / sqrt(2) ‘S’: \[\[1, 0], \[0 , 1j]] ‘T’: \[\[1, 0], \[0, (1+1j) / sqrt(2)]] ‘0’: \[\[1, 0], \[0, 0]] ‘1’: \[\[0, 0], \[0, 1]] ‘+’: \[\[0.5, 0.5], \[0.5 , 0.5]] ‘-’: \[\[0.5, -0.5], \[-0.5 , 0.5]] ‘r’: \[\[0.5, -0.5j], \[0.5j , 0.5]] ‘l’: \[\[0.5, 0.5j], \[-0.5j , 0.5]] + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if operator is a unitary matrix. + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the matrix power of the operator. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power to raise the matrix to. + +**Returns** + +the resulting operator `O ** n`. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the operator are not equal. + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### reverse\_qargs + + + +`reverse_qargs()` + +Return an Operator with reversed subsystem ordering. + +For a tensor product operator this is equivalent to reversing the order of tensor product subsystems. For an operator $A = A_{n-1} \otimes ... \otimes A_0$ the returned operator will be $A_0 \otimes ... \otimes A_{n-1}$. + +**Returns** + +the operator with reversed subsystem order. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Operator. + +**Parameters** + +**other** ([*Operator*](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – a Operator object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Operator, and $b$ is the other Operator. + +**Return type** + +[Operator](#qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a UnitaryGate instruction. + +### to\_matrix + + + +`to_matrix()` + +Convert operator to NumPy matrix. + +### to\_operator + + + +`to_operator()` + +Convert operator to matrix operator class + +**Return type** + +[*Operator*](#qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose of the Operator. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.PTM.md b/docs/api/qiskit/0.46/qiskit.quantum_info.PTM.md new file mode 100644 index 00000000000..4731d769bb8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.PTM.md @@ -0,0 +1,403 @@ +--- +title: PTM +description: API reference for qiskit.quantum_info.PTM +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.PTM +--- + +# PTM + + + +`qiskit.quantum_info.PTM(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/channel/ptm.py "view source code") + +Bases: `QuantumChannel` + +Pauli Transfer Matrix (PTM) representation of a Quantum Channel. + +The PTM representation of an $n$-qubit quantum channel $\mathcal{E}$ is an $n$-qubit [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") $R$ defined with respect to vectorization in the Pauli basis instead of column-vectorization. The elements of the PTM $R$ are given by + +$$ +R_{i,j} = \frac{1}{2^n} \mbox{Tr}\left[P_i \mathcal{E}(P_j) \right] +$$ + +where $[P_0, P_1, ..., P_{4^{n}-1}]$ is the $n$-qubit Pauli basis in lexicographic order. + +Evolution of a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ with respect to the PTM is given by + +$$ +|\mathcal{E}(\rho)\rangle\!\rangle_P = S_P |\rho\rangle\!\rangle_P +$$ + +where $|A\rangle\!\rangle_P$ denotes vectorization in the Pauli basis $\langle i | A\rangle\!\rangle_P = \sqrt{\frac{1}{2^n}} \mbox{Tr}[P_i A]$. + +See reference \[1] for further details. + +**References** + +1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015). [arXiv:1111.6950 \[quant-ph\]](https://arxiv.org/abs/1111.6950) + +Initialize a PTM quantum channel operator. + +**Parameters** + +* **or** (*data (*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Instruction or BaseOperator or matrix): data to initialize superoperator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input subsystem dimensions. \[Default: None] +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the output subsystem dimensions. \[Default: None] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit channel or cannot be initialized as a PTM. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. The PTM representation is only valid for N-qubit channels. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return data. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint quantum channel. + + + This is equivalent to the matrix Hermitian conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the adjoint channel $\mathcal{{E}}^\dagger$ is $S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger$. + + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another PTM. + +**Parameters** + +* **other** ([*PTM*](#qiskit.quantum_info.PTM "qiskit.quantum_info.PTM")) – a PTM object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed PTM. + +**Return type** + +[PTM](#qiskit.quantum_info.PTM "qiskit.quantum_info.PTM") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.PTM.dot "qiskit.quantum_info.PTM.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.PTM.dot "qiskit.quantum_info.PTM.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate quantum channel. + + + This is equivalent to the matrix complex conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the conjugate channel $\overline{{\mathcal{{E}}}}$ is $S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}$. + + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another PTM. + +**Parameters** + +**other** ([*PTM*](#qiskit.quantum_info.PTM "qiskit.quantum_info.PTM")) – a PTM object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current PTM, and $b$ is the other PTM. + +**Return type** + +[PTM](#qiskit.quantum_info.PTM "qiskit.quantum_info.PTM") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_cp + + + +`is_cp(atol=None, rtol=None)` + +Test if Choi-matrix is completely-positive (CP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_cptp + + + +`is_cptp(atol=None, rtol=None)` + +Return True if completely-positive trace-preserving (CPTP). + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_tp + + + +`is_tp(atol=None, rtol=None)` + +Test if a channel is trace-preserving (TP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if QuantumChannel is a unitary channel. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the quantum channel. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power exponent. + +**Returns** + +the channel $\mathcal{{E}} ^n$. + +**Return type** + +[SuperOp](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the SuperOp are not equal. + + + For non-positive or non-integer exponents the power is defined as the matrix power of the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{{E}}$, the SuperOp of the powered channel $\mathcal{{E}}^\n$ is $S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n$. + + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another PTM. + +**Parameters** + +**other** ([*PTM*](#qiskit.quantum_info.PTM "qiskit.quantum_info.PTM")) – a PTM object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current PTM, and $b$ is the other PTM. + +**Return type** + +[PTM](#qiskit.quantum_info.PTM "qiskit.quantum_info.PTM") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a Kraus or UnitaryGate circuit instruction. + +If the channel is unitary it will be added as a unitary gate, otherwise it will be added as a kraus simulator instruction. + +**Returns** + +A kraus instruction for the channel. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit CPTP quantum channel. + +### to\_operator + + + +`to_operator()` + +Try to convert channel to a unitary representation Operator. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose quantum channel. + + + This is equivalent to the matrix transpose in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation, ie. for a channel $\mathcal{E}$, the SuperOp of the transpose channel $\mathcal{{E}}^T$ is $S_{mathcal{E}^T} = S_{\mathcal{E}}^T$. + + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Pauli.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Pauli.md new file mode 100644 index 00000000000..7200a492d18 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Pauli.md @@ -0,0 +1,589 @@ +--- +title: Pauli +description: API reference for qiskit.quantum_info.Pauli +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Pauli +--- + +# Pauli + + + +`qiskit.quantum_info.Pauli(data=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/pauli.py "view source code") + +Bases: `BasePauli` + +N-qubit Pauli operator. + +This class represents an operator $P$ from the full $n$-qubit *Pauli* group + +$$ +P = (-i)^{q} P_{n-1} \otimes ... \otimes P_{0} +$$ + +where $q\in \mathbb{Z}_4$ and $P_i \in \{I, X, Y, Z\}$ are single-qubit Pauli matrices: + +$$ +I = \begin{pmatrix} 1 & 0 \\ 0 & 1 \end{pmatrix}, +X = \begin{pmatrix} 0 & 1 \\ 1 & 0 \end{pmatrix}, +Y = \begin{pmatrix} 0 & -i \\ i & 0 \end{pmatrix}, +Z = \begin{pmatrix} 1 & 0 \\ 0 & -1 \end{pmatrix}. +$$ + +**Initialization** + +A Pauli object can be initialized in several ways: + +> **`Pauli(obj)`** +> +> where `obj` is a Pauli string, `Pauli` or [`ScalarOp`](qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp") operator, or a Pauli gate or `QuantumCircuit` containing only Pauli gates. +> +> **`Pauli((z, x, phase))`** +> +> where `z` and `x` are boolean `numpy.ndarrays` and `phase` is an integer in `[0, 1, 2, 3]`. +> +> **`Pauli((z, x))`** +> +> equivalent to `Pauli((z, x, 0))` with trivial phase. + +**String representation** + +An $n$-qubit Pauli may be represented by a string consisting of $n$ characters from `['I', 'X', 'Y', 'Z']`, and optionally phase coefficient in $['', '-i', '-', 'i']$. For example: `XYZ` or `'-iZIZ'`. + +In the string representation qubit-0 corresponds to the right-most Pauli character, and qubit-$(n-1)$ to the left-most Pauli character. For example `'XYZ'` represents $X\otimes Y \otimes Z$ with `'Z'` on qubit-0, `'Y'` on qubit-1, and `'X'` on qubit-2. + +The string representation can be converted to a `Pauli` using the class initialization (`Pauli('-iXYZ')`). A `Pauli` object can be converted back to the string representation using the [`to_label()`](#qiskit.quantum_info.Pauli.to_label "qiskit.quantum_info.Pauli.to_label") method or `str(pauli)`. + + + Using `str` to convert a `Pauli` to a string will truncate the returned string for large numbers of qubits while [`to_label()`](#qiskit.quantum_info.Pauli.to_label "qiskit.quantum_info.Pauli.to_label") will return the full string with no truncation. The default truncation length is 50 characters. The default value can be changed by setting the class `__truncate__` attribute to an integer value. If set to `0` no truncation will be performed. + + +**Array Representation** + +The internal data structure of an $n$-qubit Pauli is two length-$n$ boolean vectors $z \in \mathbb{Z}_2^N$, $x \in \mathbb{Z}_2^N$, and an integer $q \in \mathbb{Z}_4$ defining the Pauli operator + +$$ +P = (-i)^{q + z\cdot x} Z^z \cdot X^x. +$$ + +The $k$-th qubit corresponds to the $k$-th entry in the $z$ and $x$ arrays + +$$ +\begin{aligned} +P &= P_{n-1} \otimes ... \otimes P_{0} \\ +P_k &= (-i)^{z[k] * x[k]} Z^{z[k]}\cdot X^{x[k]} +\end{aligned} +$$ + +where `z[k] = P.z[k]`, `x[k] = P.x[k]` respectively. + +The $z$ and $x$ arrays can be accessed and updated using the [`z`](#qiskit.quantum_info.Pauli.z "qiskit.quantum_info.Pauli.z") and [`x`](#qiskit.quantum_info.Pauli.x "qiskit.quantum_info.Pauli.x") properties respectively. The phase integer $q$ can be accessed and updated using the [`phase`](#qiskit.quantum_info.Pauli.phase "qiskit.quantum_info.Pauli.phase") property. + +**Matrix Operator Representation** + +Pauli’s can be converted to $(2^n, 2^n)$ [`Operator`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") using the `to_operator()` method, or to a dense or sparse complex matrix using the [`to_matrix()`](#qiskit.quantum_info.Pauli.to_matrix "qiskit.quantum_info.Pauli.to_matrix") method. + +**Data Access** + +The individual qubit Paulis can be accessed and updated using the `[]` operator which accepts integer, lists, or slices for selecting subsets of Paulis. Note that selecting subsets of Pauli’s will discard the phase of the current Pauli. + +For example + +```python +p = Pauli('-iXYZ') + +print('P[0] =', repr(P[0])) +print('P[1] =', repr(P[1])) +print('P[2] =', repr(P[2])) +print('P[:] =', repr(P[:])) +print('P[::-1] =, repr(P[::-1])) +``` + +Initialize the Pauli. + +When using the symplectic array input data both z and x arguments must be provided, however the first (z) argument can be used alone for string label, Pauli operator, or ScalarOp input data. + +**Parameters** + +**data** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*ScalarOp*](qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp")) – input data for Pauli. If input is a tuple it must be of the form `(z, x)` or (z, x, phase)\`\` where `z` and `x` are boolean Numpy arrays, and phase is an integer from Z\_4. If input is a string, it must be a concatenation of a phase and a Pauli string (e.g. ‘XYZ’, ‘-iZIZ’) where a phase string is a combination of at most three characters from \[‘+’, ‘-’, ‘’], \[‘1’, ‘’], and \[‘i’, ‘j’, ‘’] in this order, e.g. ‘’, ‘-1j’ while a Pauli string is 1 or more characters of ‘I’, ‘X’, ‘Y’ or ‘Z’, e.g. ‘Z’, ‘XIYY’. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input array is invalid shape. + +## Attributes + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### name + +Unique string identifier for operation type. + + + +### num\_clbits + +Number of classical bits. + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### phase + +Return the group phase exponent for the Pauli. + + + +### qargs + +Return the qargs for the operator. + + + +### settings + +Return settings. + + + +### x + +The x vector for the Pauli. + + + +### z + +The z vector for the Pauli. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the Operator. + +### anticommutes + + + +`anticommutes(other, qargs=None)` + +Return True if other Pauli anticommutes with self. + +**Parameters** + +* **other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – another Pauli operator. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to apply dot product on (default: None). + +**Returns** + +True if Pauli’s anticommute, False if they commute. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### commutes + + + +`commutes(other, qargs=None)` + +Return True if the Pauli commutes with other. + +**Parameters** + +* **other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*PauliList*](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another Pauli operator. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to apply dot product on (default: None). + +**Returns** + +True if Pauli’s commute, False if they anti-commute. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### compose + + + +`compose(other, qargs=None, front=False, inplace=False)` + +Return the operator composition with another Pauli. + +**Parameters** + +* **other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – a Pauli object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, qubits to apply dot product on (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True update in-place (default: False). + +**Returns** + +The composed Pauli. + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while [`dot()`](#qiskit.quantum_info.Pauli.dot "qiskit.quantum_info.Pauli.dot") is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Pauli.dot "qiskit.quantum_info.Pauli.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate of each Pauli in the list. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### delete + + + +`delete(qubits)` + +Return a Pauli with qubits deleted. + +**Parameters** + +**qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to delete from Pauli. + +**Returns** + +the resulting Pauli with the specified qubits removed. + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if ind is out of bounds for the array size or number of qubits. + +### dot + + + +`dot(other, qargs=None, inplace=False)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, qubits to apply dot product on (default: None). +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True update in-place (default: False). + +**Returns** + +The operator self \* other. + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +### equiv + + + +`equiv(other)` + +Return True if Pauli’s are equivalent up to group phase. + +**Parameters** + +**other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – an operator object. + +**Returns** + +True if the Pauli’s are equivalent up to group phase. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### evolve + + + +`evolve(other, qargs=None, frame='h')` + +Performs either Heisenberg (default) or Schrödinger picture evolution of the Pauli by a Clifford and returns the evolved Pauli. + +Schrödinger picture evolution can be chosen by passing parameter `frame='s'`. This option yields a faster calculation. + +Heisenberg picture evolves the Pauli as $P^\prime = C^\dagger.P.C$. + +Schrödinger picture evolves the Pauli as $P^\prime = C.P.C^\dagger$. + +**Parameters** + +* **other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The Clifford operator to evolve by. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list of qubits to apply the Clifford to. +* **frame** (*string*) – `'h'` for Heisenberg (default) or `'s'` for +* **framework.** (*Schrödinger*) – + +**Returns** + +the Pauli $C^\dagger.P.C$ (Heisenberg picture) or the Pauli $C.P.C^\dagger$ (Schrödinger picture). + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the Clifford number of qubits and qargs don’t match. + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Pauli. + +**Parameters** + +**other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – a Pauli object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Pauli, and $b$ is the other Pauli. + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### insert + + + +`insert(qubits, value)` + +Insert a Pauli at specific qubit value. + +**Parameters** + +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits index to insert at. +* **value** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – value to insert. + +**Returns** + +the resulting Pauli with the entries inserted. + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the insertion qubits are invalid. + +### inverse + + + +`inverse()` + +Return the inverse of the Pauli. + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the compose of a operator with itself n times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of times to compose with self (n>0). + +**Returns** + +the n-times composed operator. + +**Return type** + +[Clifford](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the operator are not equal, or the power is not a positive integer. + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### set\_truncation + + + +`classmethod set_truncation(val)` + +Set the max number of Pauli characters to display before truncation/ + +**Parameters** + +**val** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of characters. + + + Truncation will be disabled if the truncation value is set to 0. + + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Pauli. + +**Parameters** + +**other** ([*Pauli*](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – a Pauli object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Pauli, and $b$ is the other Pauli. + +**Return type** + +[Pauli](#qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to Pauli circuit instruction. + +### to\_label + + + +`to_label()` + +Convert a Pauli to a string label. + + + The difference between to\_label and `__str__()` is that the later will truncate the output for large numbers of qubits. + + +**Returns** + +the Pauli string label. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### to\_matrix + + + +`to_matrix(sparse=False)` + +Convert to a Numpy array or sparse CSR matrix. + +**Parameters** + +**sparse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True return sparse CSR matrices, otherwise return dense Numpy arrays (default: False). + +**Returns** + +The Pauli matrix. + +**Return type** + +array + +### transpose + + + +`transpose()` + +Return the transpose of each Pauli in the list. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.PauliList.md b/docs/api/qiskit/0.46/qiskit.quantum_info.PauliList.md new file mode 100644 index 00000000000..7c5519e0e3f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.PauliList.md @@ -0,0 +1,865 @@ +--- +title: PauliList +description: API reference for qiskit.quantum_info.PauliList +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.PauliList +--- + +# PauliList + + + +`qiskit.quantum_info.PauliList(data)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/pauli_list.py "view source code") + +Bases: `BasePauli`, `LinearMixin`, `GroupMixin` + +List of N-qubit Pauli operators. + +This class is an efficient representation of a list of [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") operators. It supports 1D numpy array indexing returning a [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") for integer indexes or a [`PauliList`](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") for slice or list indices. + +**Initialization** + +A PauliList object can be initialized in several ways. + +> **`PauliList(list[str])`** +> +> where strings are same representation with [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli"). +> +> **`PauliList(Pauli) and PauliList(list[Pauli])`** +> +> where Pauli is [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli"). +> +> **`PauliList.from_symplectic(z, x, phase)`** +> +> where `z` and `x` are 2 dimensional boolean `numpy.ndarrays` and `phase` is an integer in `[0, 1, 2, 3]`. + +For example, + +```python +import numpy as np + +from qiskit.quantum_info import Pauli, PauliList + +# 1. init from list[str] +pauli_list = PauliList(["II", "+ZI", "-iYY"]) +print("1. ", pauli_list) + +pauli1 = Pauli("iXI") +pauli2 = Pauli("iZZ") + +# 2. init from Pauli +print("2. ", PauliList(pauli1)) + +# 3. init from list[Pauli] +print("3. ", PauliList([pauli1, pauli2])) + +# 4. init from np.ndarray +z = np.array([[True, True], [False, False]]) +x = np.array([[False, True], [True, False]]) +phase = np.array([0, 1]) +pauli_list = PauliList.from_symplectic(z, x, phase) +print("4. ", pauli_list) +``` + +```python +1. ['II', 'ZI', '-iYY'] +2. ['iXI'] +3. ['iXI', 'iZZ'] +4. ['YZ', '-iIX'] +``` + +**Data Access** + +The individual Paulis can be accessed and updated using the `[]` operator which accepts integer, lists, or slices for selecting subsets of PauliList. If integer is given, it returns Pauli not PauliList. + +```python +pauli_list = PauliList(["XX", "ZZ", "IZ"]) +print("Integer: ", repr(pauli_list[1])) +print("List: ", repr(pauli_list[[0, 2]])) +print("Slice: ", repr(pauli_list[0:2])) +``` + +```python +Integer: Pauli('ZZ') +List: PauliList(['XX', 'IZ']) +Slice: PauliList(['XX', 'ZZ']) +``` + +**Iteration** + +Rows in the Pauli table can be iterated over like a list. Iteration can also be done using the label or matrix representation of each row using the [`label_iter()`](#qiskit.quantum_info.PauliList.label_iter "qiskit.quantum_info.PauliList.label_iter") and [`matrix_iter()`](#qiskit.quantum_info.PauliList.matrix_iter "qiskit.quantum_info.PauliList.matrix_iter") methods. + +Initialize the PauliList. + +**Parameters** + +**data** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – input data for Paulis. If input is a list each item in the list must be a Pauli object or Pauli str. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input array is invalid shape. + +**Additional Information:** + +The input array is not copied so multiple Pauli tables can share the same underlying array. + +## Attributes + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### phase + +Return the phase exponent of the PauliList. + + + +### qargs + +Return the qargs for the operator. + + + +### settings + +Return settings. + + + +### shape + +The full shape of the `array()` + + + +### size + +The number of Pauli rows in the table. + + + +### x + +The x array for the symplectic representation. + + + +### z + +The z array for the symplectic representation. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of each Pauli in the list. + +### anticommutes + + + +`anticommutes(other, qargs=None)` + +Return `True` if other Pauli that anticommutes with other. + +**Parameters** + +* **other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another PauliList operator. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to apply dot product on (default: `None`). + +**Returns** + +`True` if Paulis anticommute, `False` if they commute. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### anticommutes\_with\_all + + + +`anticommutes_with_all(other)` + +Return indexes of rows that commute other. + +If `other` is a multi-row Pauli list the returned vector indexes rows of the current PauliList that anti-commute with *all* Paulis in other. If no rows satisfy the condition the returned array will be empty. + +**Parameters** + +**other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – a single Pauli or multi-row PauliList. + +**Returns** + +index array of the anti-commuting rows. + +**Return type** + +array + +### argsort + + + +`argsort(weight=False, phase=False)` + +Return indices for sorting the rows of the table. + +The default sort method is lexicographic sorting by qubit number. By using the weight kwarg the output can additionally be sorted by the number of non-identity terms in the Pauli, where the set of all Paulis of a given weight are still ordered lexicographically. + +**Parameters** + +* **weight** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optionally sort by weight if `True` (Default: `False`). +* **phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optionally sort by phase before weight or order (Default: `False`). + +**Returns** + +the indices for sorting the table. + +**Return type** + +array + +### commutes + + + +`commutes(other, qargs=None)` + +Return True for each Pauli that commutes with other. + +**Parameters** + +* **other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another PauliList operator. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to apply dot product on (default: `None`). + +**Returns** + +`True` if Paulis commute, `False` if they anti-commute. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### commutes\_with\_all + + + +`commutes_with_all(other)` + +Return indexes of rows that commute `other`. + +If `other` is a multi-row Pauli list the returned vector indexes rows of the current PauliList that commute with *all* Paulis in other. If no rows satisfy the condition the returned array will be empty. + +**Parameters** + +**other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – a single Pauli or multi-row PauliList. + +**Returns** + +index array of the commuting rows. + +**Return type** + +array + +### compose + + + +`compose(other, qargs=None, front=False, inplace=False)` + +Return the composition self∘other for each Pauli in the list. + +**Parameters** + +* **other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another PauliList. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to apply dot product on (Default: `None`). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True use dot composition method \[default: `False`]. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` update in-place (default: `False`). + +**Returns** + +the list of composed Paulis. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list, or has the wrong number of qubits for the specified `qargs`. + +### conjugate + + + +`conjugate()` + +Return the conjugate of each Pauli in the list. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### delete + + + +`delete(ind, qubit=False)` + +Return a copy with Pauli rows deleted from table. + +When deleting qubits the qubit index is the same as the column index of the underlying `X` and `Z` arrays. + +**Parameters** + +* **ind** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – index(es) to delete. +* **qubit** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True` delete qubit columns, otherwise delete Pauli rows (Default: `False`). + +**Returns** + +the resulting table with the entries removed. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if `ind` is out of bounds for the array size or number of qubits. + +### dot + + + +`dot(other, qargs=None, inplace=False)` + +Return the composition other∘self for each Pauli in the list. + +**Parameters** + +* **other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another PauliList. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – qubits to apply dot product on (Default: `None`). +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True update in-place (default: `False`). + +**Returns** + +the list of composed Paulis. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list, or has the wrong number of qubits for the specified `qargs`. + +### equiv + + + +`equiv(other)` + +Entrywise comparison of Pauli equivalence up to global phase. + +**Parameters** + +**other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") *or*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – a comparison object. + +**Returns** + +**An array of `True` or `False` for entrywise equivalence** + +of the current table. + +**Return type** + +np.ndarray + +### evolve + + + +`evolve(other, qargs=None, frame='h')` + +Performs either Heisenberg (default) or Schrödinger picture evolution of the Pauli by a Clifford and returns the evolved Pauli. + +Schrödinger picture evolution can be chosen by passing parameter `frame='s'`. This option yields a faster calculation. + +Heisenberg picture evolves the Pauli as $P^\prime = C^\dagger.P.C$. + +Schrödinger picture evolves the Pauli as $P^\prime = C.P.C^\dagger$. + +**Parameters** + +* **other** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The Clifford operator to evolve by. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list of qubits to apply the Clifford to. +* **frame** (*string*) – `'h'` for Heisenberg (default) or `'s'` for Schrödinger framework. + +**Returns** + +the Pauli $C^\dagger.P.C$ (Heisenberg picture) or the Pauli $C.P.C^\dagger$ (Schrödinger picture). + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the Clifford number of qubits and qargs don’t match. + +### expand + + + +`expand(other)` + +Return the expand product of each Pauli in the list. + +**Parameters** + +**other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another PauliList. + +**Returns** + +the list of tensor product Paulis. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list. + +### from\_symplectic + + + +`classmethod from_symplectic(z, x, phase=0)` + +Construct a PauliList from a symplectic data. + +**Parameters** + +* **z** (*np.ndarray*) – 2D boolean Numpy array. +* **x** (*np.ndarray*) – 2D boolean Numpy array. +* **phase** (*np.ndarray or None*) – Optional, 1D integer array from Z\_4. + +**Returns** + +the constructed PauliList. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +### group\_commuting + + + +`group_commuting(qubit_wise=False)` + +Partition a PauliList into sets of commuting Pauli strings. + +**Parameters** + +**qubit\_wise** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – + +whether the commutation rule is applied to the whole operator, or on a per-qubit basis. For example: + +```python +>>> from qiskit.quantum_info import PauliList +>>> op = PauliList(["XX", "YY", "IZ", "ZZ"]) +>>> op.group_commuting() +[PauliList(['XX', 'YY']), PauliList(['IZ', 'ZZ'])] +>>> op.group_commuting(qubit_wise=True) +[PauliList(['XX']), PauliList(['YY']), PauliList(['IZ', 'ZZ'])] +``` + +**Returns** + +List of PauliLists where each PauliList contains commuting Pauli operators. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")] + +### group\_qubit\_wise\_commuting + + + +`group_qubit_wise_commuting()` + +Partition a PauliList into sets of mutually qubit-wise commuting Pauli strings. + +**Returns** + +List of PauliLists where each PauliList contains commutable Pauli operators. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")] + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### insert + + + +`insert(ind, value, qubit=False)` + +Insert Paulis into the table. + +When inserting qubits the qubit index is the same as the column index of the underlying `X` and `Z` arrays. + +**Parameters** + +* **ind** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – index to insert at. +* **value** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – values to insert. +* **qubit** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True` insert qubit columns, otherwise insert Pauli rows (Default: `False`). + +**Returns** + +the resulting table with the entries inserted. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the insertion index is invalid. + +### inverse + + + +`inverse()` + +Return the inverse of each Pauli in the list. + +### label\_iter + + + +`label_iter()` + +Return a label representation iterator. + +This is a lazy iterator that converts each row into the string label only as it is used. To convert the entire table to labels use the [`to_labels()`](#qiskit.quantum_info.PauliList.to_labels "qiskit.quantum_info.PauliList.to_labels") method. + +**Returns** + +label iterator object for the PauliList. + +**Return type** + +LabelIterator + +### matrix\_iter + + + +`matrix_iter(sparse=False)` + +Return a matrix representation iterator. + +This is a lazy iterator that converts each row into the Pauli matrix representation only as it is used. To convert the entire table to matrices use the [`to_matrix()`](#qiskit.quantum_info.PauliList.to_matrix "qiskit.quantum_info.PauliList.to_matrix") method. + +**Parameters** + +**sparse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – optionally return sparse CSR matrices if `True`, otherwise return Numpy array matrices (Default: `False`) + +**Returns** + +matrix iterator object for the PauliList. + +**Return type** + +MatrixIterator + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the compose of a operator with itself n times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of times to compose with self (n>0). + +**Returns** + +the n-times composed operator. + +**Return type** + +[Clifford](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the operator are not equal, or the power is not a positive integer. + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### sort + + + +`sort(weight=False, phase=False)` + +Sort the rows of the table. + +The default sort method is lexicographic sorting by qubit number. By using the weight kwarg the output can additionally be sorted by the number of non-identity terms in the Pauli, where the set of all Paulis of a given weight are still ordered lexicographically. + +**Example** + +Consider sorting all a random ordering of all 2-qubit Paulis + +```python +from numpy.random import shuffle +from qiskit.quantum_info.operators import PauliList + +# 2-qubit labels +labels = ['II', 'IX', 'IY', 'IZ', 'XI', 'XX', 'XY', 'XZ', + 'YI', 'YX', 'YY', 'YZ', 'ZI', 'ZX', 'ZY', 'ZZ'] +# Shuffle Labels +shuffle(labels) +pt = PauliList(labels) +print('Initial Ordering') +print(pt) + +# Lexicographic Ordering +srt = pt.sort() +print('Lexicographically sorted') +print(srt) + +# Weight Ordering +srt = pt.sort(weight=True) +print('Weight sorted') +print(srt) +``` + +```python +Initial Ordering +['YX', 'ZZ', 'XZ', 'YI', 'YZ', 'II', 'XX', 'XI', 'XY', 'YY', 'IX', 'IZ', + 'ZY', 'ZI', 'ZX', 'IY'] +Lexicographically sorted +['II', 'IX', 'IY', 'IZ', 'XI', 'XX', 'XY', 'XZ', 'YI', 'YX', 'YY', 'YZ', + 'ZI', 'ZX', 'ZY', 'ZZ'] +Weight sorted +['II', 'IX', 'IY', 'IZ', 'XI', 'YI', 'ZI', 'XX', 'XY', 'XZ', 'YX', 'YY', + 'YZ', 'ZX', 'ZY', 'ZZ'] +``` + +**Parameters** + +* **weight** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – optionally sort by weight if `True` (Default: `False`). +* **phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optionally sort by phase before weight or order (Default: `False`). + +**Returns** + +a sorted copy of the original table. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +### tensor + + + +`tensor(other)` + +Return the tensor product with each Pauli in the list. + +**Parameters** + +**other** ([*PauliList*](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")) – another PauliList. + +**Returns** + +the list of tensor product Paulis. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to a PauliList, does not have either 1 or the same number of Paulis as the current list. + +### to\_labels + + + +`to_labels(array=False)` + +Convert a PauliList to a list Pauli string labels. + +For large PauliLists converting using the `array=True` kwarg will be more efficient since it allocates memory for the full Numpy array of labels in advance. + +| Label | Symplectic | Matrix | +| ----- | ---------- | ----------------------------------------------- | +| `"I"` | $[0, 0]$ | $\begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}$ | +| `"X"` | $[1, 0]$ | $\begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix}$ | +| `"Y"` | $[1, 1]$ | $\begin{bmatrix} 0 & -i \\ i & 0 \end{bmatrix}$ | +| `"Z"` | $[0, 1]$ | $\begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}$ | + +**Parameters** + +**array** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – return a Numpy array if `True`, otherwise return a list (Default: `False`). + +**Returns** + +The rows of the PauliList in label form. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") or array + +### to\_matrix + + + +`to_matrix(sparse=False, array=False)` + +Convert to a list or array of Pauli matrices. + +For large PauliLists converting using the `array=True` kwarg will be more efficient since it allocates memory a full rank-3 Numpy array of matrices in advance. + +| Label | Symplectic | Matrix | +| ----- | ---------- | ----------------------------------------------- | +| `"I"` | $[0, 0]$ | $\begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}$ | +| `"X"` | $[1, 0]$ | $\begin{bmatrix} 0 & 1 \\ 1 & 0 \end{bmatrix}$ | +| `"Y"` | $[1, 1]$ | $\begin{bmatrix} 0 & -i \\ i & 0 \end{bmatrix}$ | +| `"Z"` | $[0, 1]$ | $\begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}$ | + +**Parameters** + +* **sparse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True` return sparse CSR matrices, otherwise return dense Numpy arrays (Default: `False`). +* **array** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – return as rank-3 numpy array if `True`, otherwise return a list of Numpy arrays (Default: `False`). + +**Returns** + +A list of dense Pauli matrices if ```array=False` and ``sparse=False`. list: A list of sparse Pauli matrices if ``array=False``` and `sparse=True`. array: A dense rank-3 array of Pauli matrices if `array=True`. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +### transpose + + + +`transpose()` + +Return the transpose of each Pauli in the list. + +### unique + + + +`unique(return_index=False, return_counts=False)` + +Return unique Paulis from the table. + +**Example** + +```python +from qiskit.quantum_info.operators import PauliList + +pt = PauliList(['X', 'Y', '-X', 'I', 'I', 'Z', 'X', 'iZ']) +unique = pt.unique() +print(unique) +``` + +```python +['X', 'Y', '-X', 'I', 'Z', 'iZ'] +``` + +**Parameters** + +* **return\_index** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, also return the indices that result in the unique array. (Default: `False`) +* **return\_counts** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, also return the number of times each unique item appears in the table. + +**Returns** + +**unique** + +the table of the unique rows. + +**unique\_indices: np.ndarray, optional** + +The indices of the first occurrences of the unique values in the original array. Only provided if `return_index` is `True`. + +**unique\_counts: np.array, optional** + +The number of times each of the unique values comes up in the original array. Only provided if `return_counts` is `True`. + +**Return type** + +[PauliList](#qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Quaternion.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Quaternion.md new file mode 100644 index 00000000000..2612186176d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Quaternion.md @@ -0,0 +1,126 @@ +--- +title: Quaternion +description: API reference for qiskit.quantum_info.Quaternion +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Quaternion +--- + +# Quaternion + + + +`qiskit.quantum_info.Quaternion(data)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/quaternion.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A class representing a Quaternion. + +## Methods + +### from\_axis\_rotation + + + +`classmethod from_axis_rotation(angle, axis)` + +Return quaternion for rotation about given axis. + +**Parameters** + +* **angle** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Angle in radians. +* **axis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Axis for rotation + +**Returns** + +Quaternion for axis rotation. + +**Return type** + +[Quaternion](#qiskit.quantum_info.Quaternion "qiskit.quantum_info.Quaternion") + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – Invalid input axis. + +### from\_euler + + + +`classmethod from_euler(angles, order='yzy')` + +Generate a quaternion from a set of Euler angles. + +**Parameters** + +* **angles** (*array\_like*) – Array of Euler angles. +* **order** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Order of Euler rotations. ‘yzy’ is default. + +**Returns** + +Quaternion representation of Euler rotation. + +**Return type** + +[Quaternion](#qiskit.quantum_info.Quaternion "qiskit.quantum_info.Quaternion") + +### norm + + + +`norm()` + +Norm of quaternion. + +### normalize + + + +`normalize(inplace=False)` + +Normalizes a Quaternion to unit length so that it represents a valid rotation. + +**Parameters** + +**inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Do an inplace normalization. + +**Returns** + +Normalized quaternion. + +**Return type** + +[Quaternion](#qiskit.quantum_info.Quaternion "qiskit.quantum_info.Quaternion") + +### to\_matrix + + + +`to_matrix()` + +Converts a unit-length quaternion to a rotation matrix. + +**Returns** + +Rotation matrix. + +**Return type** + +ndarray + +### to\_zyz + + + +`to_zyz()` + +Converts a unit-length quaternion to a sequence of ZYZ Euler angles. + +**Returns** + +Array of Euler angles. + +**Return type** + +ndarray + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.ScalarOp.md b/docs/api/qiskit/0.46/qiskit.quantum_info.ScalarOp.md new file mode 100644 index 00000000000..a6cd5c7fc66 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.ScalarOp.md @@ -0,0 +1,302 @@ +--- +title: ScalarOp +description: API reference for qiskit.quantum_info.ScalarOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.ScalarOp +--- + +# ScalarOp + + + +`qiskit.quantum_info.ScalarOp(dims=None, coeff=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/scalar_op.py "view source code") + +Bases: `LinearOp` + +Scalar identity operator class. + +This is a symbolic representation of an scalar identity operator on multiple subsystems. It may be used to initialize a symbolic scalar multiplication of an identity and then be implicitly converted to other kinds of operator subclasses by using the [`compose()`](#qiskit.quantum_info.ScalarOp.compose "qiskit.quantum_info.ScalarOp.compose"), [`dot()`](#qiskit.quantum_info.ScalarOp.dot "qiskit.quantum_info.ScalarOp.dot"), [`tensor()`](#qiskit.quantum_info.ScalarOp.tensor "qiskit.quantum_info.ScalarOp.tensor"), [`expand()`](#qiskit.quantum_info.ScalarOp.expand "qiskit.quantum_info.ScalarOp.expand") methods. + +Initialize an operator object. + +**Parameters** + +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – subsystem dimensions. +* **coeff** (*Number*) – scalar coefficient for the identity operator (Default: 1). + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the optional coefficient is invalid. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### coeff + +Return the coefficient + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the Operator. + +**Return type** + +*Self* + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another ScalarOp. + +**Parameters** + +* **other** ([*ScalarOp*](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp")) – a ScalarOp object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed ScalarOp. + +**Return type** + +[ScalarOp](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.ScalarOp.dot "qiskit.quantum_info.ScalarOp.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.ScalarOp.dot "qiskit.quantum_info.ScalarOp.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate of the ScalarOp. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another ScalarOp. + +**Parameters** + +**other** ([*ScalarOp*](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp")) – a ScalarOp object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current ScalarOp, and $b$ is the other ScalarOp. + +**Return type** + +[ScalarOp](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if operator is a unitary matrix. + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the ScalarOp. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the exponent for the scalar op. + +**Returns** + +the `coeff ** n` ScalarOp. + +**Return type** + +[ScalarOp](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp") + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another ScalarOp. + +**Parameters** + +**other** ([*ScalarOp*](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp")) – a ScalarOp object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current ScalarOp, and $b$ is the other ScalarOp. + +**Return type** + +[ScalarOp](#qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_matrix + + + +`to_matrix()` + +Convert to a Numpy matrix. + +### to\_operator + + + +`to_operator()` + +Convert to an Operator object. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose of the ScalarOp. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.SparsePauliOp.md b/docs/api/qiskit/0.46/qiskit.quantum_info.SparsePauliOp.md new file mode 100644 index 00000000000..951973fa0e1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.SparsePauliOp.md @@ -0,0 +1,881 @@ +--- +title: SparsePauliOp +description: API reference for qiskit.quantum_info.SparsePauliOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.SparsePauliOp +--- + +# SparsePauliOp + + + +`qiskit.quantum_info.SparsePauliOp(data, coeffs=None, *, ignore_pauli_phase=False, copy=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/sparse_pauli_op.py "view source code") + +Bases: `LinearOp` + +Sparse N-qubit operator in a Pauli basis representation. + +This is a sparse representation of an N-qubit matrix [`Operator`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") in terms of N-qubit [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") and complex coefficients. + +It can be used for performing operator arithmetic for hundred of qubits if the number of non-zero Pauli basis terms is sufficiently small. + +The Pauli basis components are stored as a [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") object and can be accessed using the [`paulis`](#qiskit.quantum_info.SparsePauliOp.paulis "qiskit.quantum_info.SparsePauliOp.paulis") attribute. The coefficients are stored as a complex Numpy array vector and can be accessed using the [`coeffs`](#qiskit.quantum_info.SparsePauliOp.coeffs "qiskit.quantum_info.SparsePauliOp.coeffs") attribute. + +**Data type of coefficients** + +The default `dtype` of the internal `coeffs` Numpy array is `complex128`. Users can configure this by passing `np.ndarray` with a different dtype. For example, a parameterized [`SparsePauliOp`](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") can be made as follows: + +```python +>>> import numpy as np +>>> from qiskit.circuit import ParameterVector +>>> from qiskit.quantum_info import SparsePauliOp + +>>> SparsePauliOp(["II", "XZ"], np.array(ParameterVector("a", 2))) +SparsePauliOp(['II', 'XZ'], + coeffs=[ParameterExpression(1.0*a[0]), ParameterExpression(1.0*a[1])]) +``` + + + Parameterized [`SparsePauliOp`](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") does not support the following methods: + + * `to_matrix(sparse=True)` since `scipy.sparse` cannot have objects as elements. + * `to_operator()` since [`Operator`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") does not support objects. + * `sort`, `argsort` since [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") does not support comparison. + * `equiv` since [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") cannot be converted into complex. + * `chop` since [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") does not support absolute value. + + +Initialize an operator object. + +**Parameters** + +* **data** ([*PauliList*](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") *or*[*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") *or*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Pauli list of terms. A list of Pauli strings or a Pauli string is also allowed. + +* **coeffs** (*np.ndarray*) – + + complex coefficients for Pauli terms. + + + If `data` is a [`SparsePauliOp`](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") and `coeffs` is not `None`, the value of the `SparsePauliOp.coeffs` will be ignored, and only the passed keyword argument `coeffs` will be used. + + +* **ignore\_pauli\_phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if true, any `phase` component of a given [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") will be assumed to be zero. This is more efficient in cases where a [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") has been constructed purely for this object, and it is already known that the phases in the ZX-convention are zero. It only makes sense to pass this option when giving [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") data. (Default: False) + +* **copy** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – copy the input data if True, otherwise assign it directly, if possible. (Default: True) + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the input data or coeffs are invalid. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### coeffs + +Return the Pauli coefficients. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### parameters + +Return the free `Parameter`s in the coefficients. + + + +### paulis + +Return the PauliList. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + + + +### size + +The number of Pauli of Pauli terms in the operator. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint of the Operator. + +### apply\_layout + + + +`apply_layout(layout, num_qubits=None)` + +Apply a transpiler layout to this [`SparsePauliOp`](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +**Parameters** + +* **layout** ([*TranspileLayout*](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") *| List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Either a [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") or a list of integers. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits to expand the operator to. If not provided then if `layout` is a [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") the number of the transpiler output circuit qubits will be used by default. If `layout` is a list of integers the permutation specified will be applied without any expansion. + +**Returns** + +A new [`SparsePauliOp`](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") with the provided layout applied + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +### argsort + + + +`argsort(weight=False)` + +Return indices for sorting the rows of the table. + +Returns the composition of permutations in the order of sorting by coefficient and sorting by Pauli. By using the weight kwarg the output can additionally be sorted by the number of non-identity terms in the Pauli, where the set of all Pauli’s of a given weight are still ordered lexicographically. + +**Example** + +Here is an example of how to use SparsePauliOp argsort. + +```python +import numpy as np +from qiskit.quantum_info import SparsePauliOp + +# 2-qubit labels +labels = ["XX", "XX", "XX", "YI", "II", "XZ", "XY", "XI"] +# coeffs +coeffs = [2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j] + +# init +spo = SparsePauliOp(labels, coeffs) +print('Initial Ordering') +print(spo) + +# Lexicographic Ordering +srt = spo.argsort() +print('Lexicographically sorted') +print(srt) + +# Lexicographic Ordering +srt = spo.argsort(weight=False) +print('Lexicographically sorted') +print(srt) + +# Weight Ordering +srt = spo.argsort(weight=True) +print('Weight sorted') +print(srt) +``` + +```python +Initial Ordering +SparsePauliOp(['XX', 'XX', 'XX', 'YI', 'II', 'XZ', 'XY', 'XI'], + coeffs=[2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j]) +Lexicographically sorted +[4 7 0 1 2 6 5 3] +Lexicographically sorted +[4 7 0 1 2 6 5 3] +Weight sorted +[4 7 3 0 1 2 6 5] +``` + +**Parameters** + +* **weight** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – optionally sort by weight if True (Default: False). +* **sorted** (*By using the weight kwarg the output can additionally be*) – +* **Pauli.** (*by the number of non-identity terms in the*) – + +**Returns** + +the indices for sorting the table. + +**Return type** + +array + +### assign\_parameters + + + +`assign_parameters(parameters, inplace=False)` + +Bind the free `Parameter`s in the coefficients to provided values. + +**Parameters** + +* **parameters** (*Mapping\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*] | Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")*]*) – The values to bind the parameters to. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `False`, a copy of the operator with the bound parameters is returned. If `True` the operator itself is modified. + +**Returns** + +A copy of the operator with bound parameters, if `inplace` is `False`, otherwise `None`. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") | None + +### chop + + + +`chop(tol=1e-14)` + +Set real and imaginary parts of the coefficients to 0 if `< tol` in magnitude. + +For example, the operator representing `1+1e-17j X + 1e-17 Y` with a tolerance larger than `1e-17` will be reduced to `1 X` whereas [`SparsePauliOp.simplify()`](#qiskit.quantum_info.SparsePauliOp.simplify "qiskit.quantum_info.SparsePauliOp.simplify") would return `1+1e-17j X`. + +If a both the real and imaginary part of a coefficient is 0 after chopping, the corresponding Pauli is removed from the operator. + +**Parameters** + +**tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The absolute tolerance to check whether a real or imaginary part should be set to 0. + +**Returns** + +This operator with chopped coefficients. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another SparsePauliOp. + +**Parameters** + +* **other** ([*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – a SparsePauliOp object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed SparsePauliOp. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.SparsePauliOp.dot "qiskit.quantum_info.SparsePauliOp.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.SparsePauliOp.dot "qiskit.quantum_info.SparsePauliOp.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate of the SparsePauliOp. + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### equiv + + + +`equiv(other, atol=None)` + +Check if two SparsePauliOp operators are equivalent. + +**Parameters** + +* **other** ([*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – an operator object. +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Absolute numerical tolerance for checking equivalence. + +**Returns** + +True if the operator is equivalent to `self`. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another SparsePauliOp. + +**Parameters** + +**other** ([*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – a SparsePauliOp object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current SparsePauliOp, and $b$ is the other SparsePauliOp. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +### from\_list + + + +`static from_list(obj, dtype=, *, num_qubits=None)` + +Construct from a list of Pauli strings and coefficients. + +For example, the 5-qubit Hamiltonian + +$$ +H = Z_1 X_4 + 2 Y_0 Y_3 +$$ + +can be constructed as + +```python +# via tuples and the full Pauli string +op = SparsePauliOp.from_list([("XIIZI", 1), ("IYIIY", 2)]) +``` + +**Parameters** + +* **obj** (*Iterable\[Tuple\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]]*) – The list of 2-tuples specifying the Pauli terms. +* **dtype** ([*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)")) – The dtype of coeffs (Default: complex). +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits of the operator (Default: None). + +**Returns** + +The SparsePauliOp representation of the Pauli terms. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If an empty list is passed and num\_qubits is None. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If num\_qubits and the objects in the input list do not match. + +### from\_operator + + + +`static from_operator(obj, atol=None, rtol=None)` + +Construct from an Operator objector. + +Note that the cost of this construction is exponential as it involves taking inner products with every element of the N-qubit Pauli basis. + +**Parameters** + +* **obj** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an N-qubit operator. +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Optional. Absolute tolerance for checking if coefficients are zero (Default: 1e-8). +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Optional. relative tolerance for checking if coefficients are zero (Default: 1e-5). + +**Returns** + +the SparsePauliOp representation of the operator. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input operator is not an N-qubit operator. + +### from\_sparse\_list + + + +`static from_sparse_list(obj, num_qubits, do_checks=True, dtype=)` + +Construct from a list of local Pauli strings and coefficients. + +Each list element is a 3-tuple of a local Pauli string, indices where to apply it, and a coefficient. + +For example, the 5-qubit Hamiltonian + +$$ +H = Z_1 X_4 + 2 Y_0 Y_3 +$$ + +can be constructed as + +```python +# via triples and local Paulis with indices +op = SparsePauliOp.from_sparse_list([("ZX", [1, 4], 1), ("YY", [0, 3], 2)], num_qubits=5) + +# equals the following construction from "dense" Paulis +op = SparsePauliOp.from_list([("XIIZI", 1), ("IYIIY", 2)]) +``` + +**Parameters** + +* **obj** (*Iterable\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*],* [*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")*]]*) – The list 3-tuples specifying the Paulis. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits of the operator. +* **do\_checks** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – The flag of checking if the input indices are not duplicated +* \*\*(\*\***Default** – True). +* **dtype** ([*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.12)")) – The dtype of coeffs (Default: complex). + +**Returns** + +The SparsePauliOp representation of the Pauli terms. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the number of qubits is incompatible with the indices of the Pauli terms. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the designated qubit is already assigned. + +### group\_commuting + + + +`group_commuting(qubit_wise=False)` + +Partition a SparsePauliOp into sets of commuting Pauli strings. + +**Parameters** + +**qubit\_wise** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – + +whether the commutation rule is applied to the whole operator, or on a per-qubit basis. For example: + +```python +>>> op = SparsePauliOp.from_list([("XX", 2), ("YY", 1), ("IZ",2j), ("ZZ",1j)]) +>>> op.group_commuting() +[SparsePauliOp(["IZ", "ZZ"], coeffs=[0.+2.j, 0.+1j]), + SparsePauliOp(["XX", "YY"], coeffs=[2.+0.j, 1.+0.j])] +>>> op.group_commuting(qubit_wise=True) +[SparsePauliOp(['XX'], coeffs=[2.+0.j]), + SparsePauliOp(['YY'], coeffs=[1.+0.j]), + SparsePauliOp(['IZ', 'ZZ'], coeffs=[0.+2.j, 0.+1.j])] +``` + +**Returns** + +**List of SparsePauliOp where each SparsePauliOp contains** + +commuting Pauli operators. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")] + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if operator is a unitary matrix. + +**Parameters** + +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Optional. Absolute tolerance for checking if coefficients are zero (Default: 1e-8). +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Optional. relative tolerance for checking if coefficients are zero (Default: 1e-5). + +**Returns** + +True if the operator is unitary, False otherwise. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### label\_iter + + + +`label_iter()` + +Return a label representation iterator. + +This is a lazy iterator that converts each term in the SparsePauliOp into a tuple (label, coeff). To convert the entire table to labels use the `to_labels()` method. + +**Returns** + +label iterator object for the SparsePauliOp. + +**Return type** + +LabelIterator + +### matrix\_iter + + + +`matrix_iter(sparse=False)` + +Return a matrix representation iterator. + +This is a lazy iterator that converts each term in the SparsePauliOp into a matrix as it is used. To convert to a single matrix use the [`to_matrix()`](#qiskit.quantum_info.SparsePauliOp.to_matrix "qiskit.quantum_info.SparsePauliOp.to_matrix") method. + +**Parameters** + +**sparse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – optionally return sparse CSR matrices if True, otherwise return Numpy array matrices (Default: False) + +**Returns** + +matrix iterator object for the PauliList. + +**Return type** + +MatrixIterator + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the compose of a operator with itself n times. + +**Parameters** + +**n** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of times to compose with self (n>0). + +**Returns** + +the n-times composed operator. + +**Return type** + +[Clifford](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the operator are not equal, or the power is not a positive integer. + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### simplify + + + +`simplify(atol=None, rtol=None)` + +Simplify PauliList by combining duplicates and removing zeros. + +**Parameters** + +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Optional. Absolute tolerance for checking if coefficients are zero (Default: 1e-8). +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Optional. relative tolerance for checking if coefficients are zero (Default: 1e-5). + +**Returns** + +the simplified SparsePauliOp operator. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +### sort + + + +`sort(weight=False)` + +Sort the rows of the table. + +After sorting the coefficients using numpy’s argsort, sort by Pauli. Pauli sort takes precedence. If Pauli is the same, it will be sorted by coefficient. By using the weight kwarg the output can additionally be sorted by the number of non-identity terms in the Pauli, where the set of all Pauli’s of a given weight are still ordered lexicographically. + +**Example** + +Here is an example of how to use SparsePauliOp sort. + +```python +import numpy as np +from qiskit.quantum_info import SparsePauliOp + +# 2-qubit labels +labels = ["XX", "XX", "XX", "YI", "II", "XZ", "XY", "XI"] +# coeffs +coeffs = [2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j] + +# init +spo = SparsePauliOp(labels, coeffs) +print('Initial Ordering') +print(spo) + +# Lexicographic Ordering +srt = spo.sort() +print('Lexicographically sorted') +print(srt) + +# Lexicographic Ordering +srt = spo.sort(weight=False) +print('Lexicographically sorted') +print(srt) + +# Weight Ordering +srt = spo.sort(weight=True) +print('Weight sorted') +print(srt) +``` + +```python +Initial Ordering +SparsePauliOp(['XX', 'XX', 'XX', 'YI', 'II', 'XZ', 'XY', 'XI'], + coeffs=[2.+1.j, 2.+2.j, 3.+0.j, 3.+0.j, 4.+0.j, 5.+0.j, 6.+0.j, 7.+0.j]) +Lexicographically sorted +SparsePauliOp(['II', 'XI', 'XX', 'XX', 'XX', 'XY', 'XZ', 'YI'], + coeffs=[4.+0.j, 7.+0.j, 2.+1.j, 2.+2.j, 3.+0.j, 6.+0.j, 5.+0.j, 3.+0.j]) +Lexicographically sorted +SparsePauliOp(['II', 'XI', 'XX', 'XX', 'XX', 'XY', 'XZ', 'YI'], + coeffs=[4.+0.j, 7.+0.j, 2.+1.j, 2.+2.j, 3.+0.j, 6.+0.j, 5.+0.j, 3.+0.j]) +Weight sorted +SparsePauliOp(['II', 'XI', 'YI', 'XX', 'XX', 'XX', 'XY', 'XZ'], + coeffs=[4.+0.j, 7.+0.j, 3.+0.j, 2.+1.j, 2.+2.j, 3.+0.j, 6.+0.j, 5.+0.j]) +``` + +**Parameters** + +* **weight** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – optionally sort by weight if True (Default: False). +* **sorted** (*By using the weight kwarg the output can additionally be*) – +* **Pauli.** (*by the number of non-identity terms in the*) – + +**Returns** + +a sorted copy of the original table. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +### sum + + + +`static sum(ops)` + +Sum of SparsePauliOps. + +This is a specialized version of the builtin `sum` function for SparsePauliOp with smaller overhead. + +**Parameters** + +**ops** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")*]*) – a list of SparsePauliOps. + +**Returns** + +the SparsePauliOp representing the sum of the input list. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input list is empty. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input list includes an object that is not SparsePauliOp. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the numbers of qubits of the objects in the input list do not match. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another SparsePauliOp. + +**Parameters** + +**other** ([*SparsePauliOp*](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – a SparsePauliOp object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current SparsePauliOp, and $b$ is the other SparsePauliOp. + +**Return type** + +[SparsePauliOp](#qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_list + + + +`to_list(array=False)` + +Convert to a list Pauli string labels and coefficients. + +For operators with a lot of terms converting using the `array=True` kwarg will be more efficient since it allocates memory for the full Numpy array of labels in advance. + +**Parameters** + +**array** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – return a Numpy array if True, otherwise return a list (Default: False). + +**Returns** + +List of pairs (label, coeff) for rows of the PauliList. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") or array + +### to\_matrix + + + +`to_matrix(sparse=False)` + +Convert to a dense or sparse matrix. + +**Parameters** + +**sparse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True return a sparse CSR matrix, otherwise return dense Numpy array (Default: False). + +**Returns** + +A dense matrix if sparse=False. csr\_matrix: A sparse matrix in CSR format if sparse=True. + +**Return type** + +array + +### to\_operator + + + +`to_operator()` + +Convert to a matrix Operator object + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose of the SparsePauliOp. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.StabilizerState.md b/docs/api/qiskit/0.46/qiskit.quantum_info.StabilizerState.md new file mode 100644 index 00000000000..1acb7f476c0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.StabilizerState.md @@ -0,0 +1,438 @@ +--- +title: StabilizerState +description: API reference for qiskit.quantum_info.StabilizerState +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.StabilizerState +--- + +# StabilizerState + + + +`qiskit.quantum_info.StabilizerState(data, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/stabilizerstate.py "view source code") + +Bases: `QuantumState` + +StabilizerState class. Stabilizer simulator using the convention from reference \[1]. Based on the internal class [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford"). + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import StabilizerState, Pauli + +# Bell state generation circuit +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) +stab = StabilizerState(qc) + +# Print the StabilizerState +print(stab) + +# Calculate the StabilizerState measurement probabilities dictionary +print (stab.probabilities_dict()) + +# Calculate expectation value of the StabilizerState +print (stab.expectation_value(Pauli('ZZ'))) +``` + +```python +StabilizerState(StabilizerTable: ['+XX', '+ZZ']) +{'00': 0.5, '11': 0.5} +1 +``` + +**References** + +1. S. Aaronson, D. Gottesman, *Improved Simulation of Stabilizer Circuits*, Phys. Rev. A 70, 052328 (2004). [arXiv:quant-ph/0406196](https://arxiv.org/abs/quant-ph/0406196) + +Initialize a StabilizerState object. + +**Parameters** + +* **or** (*data (*[*StabilizerState*](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState") *or*[*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") *or*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – qiskit.circuit.Instruction): Data from which the stabilizer state can be constructed. +* **validate** (*boolean*) – validate that the stabilizer state data is a valid Clifford. + +## Attributes + + + +### clifford + +Return StabilizerState Clifford data + + + +### dim + +Return total state dimension. + + + +### num\_qubits + +Return the number of qubits if a N-qubit state or None otherwise. + +## Methods + +### conjugate + + + +`conjugate()` + +Return the conjugate of the operator. + +### copy + + + +`copy()` + +Make a copy of current operator. + +### dims + + + +`dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### equiv + + + +`equiv(other)` + +Return True if the two generating sets generate the same stabilizer group. + +**Parameters** + +**other** ([*StabilizerState*](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState")) – another StabilizerState. + +**Returns** + +True if other has a generating set that generates the same StabilizerState. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### evolve + + + +`evolve(other, qargs=None)` + +Evolve a stabilizer state by a Clifford operator. + +**Parameters** + +* **other** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – The Clifford operator to evolve by. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list of stabilizer subsystem positions to apply the operator on. + +**Returns** + +the output stabilizer state. + +**Return type** + +[StabilizerState](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a StabilizerState. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the operator dimension does not match the specified StabilizerState subsystem dimensions. + +### expand + + + +`expand(other)` + +Return the tensor product stabilizer state other ⊗ self. + +**Parameters** + +**other** ([*StabilizerState*](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState")) – a stabilizer state object. + +**Returns** + +the tensor product operator other ⊗ self. + +**Return type** + +[StabilizerState](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a StabilizerState. + +### expectation\_value + + + +`expectation_value(oper, qargs=None)` + +Compute the expectation value of a Pauli operator. + +**Parameters** + +* **oper** ([*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")) – a Pauli operator to evaluate expval. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to apply the operator on. + +**Returns** + +the expectation value (only 0 or 1 or -1 or i or -i). + +**Return type** + +[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if oper is not a Pauli operator. + +### is\_valid + + + +`is_valid(atol=None, rtol=None)` + +Return True if a valid StabilizerState. + +### measure + + + +`measure(qargs=None)` + +Measure subsystems and return outcome and post-measure state. + +Note that this function uses the QuantumStates internal random number generator for sampling the measurement outcome. The RNG seed can be set using the [`seed()`](#qiskit.quantum_info.StabilizerState.seed "qiskit.quantum_info.StabilizerState.seed") method. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +**the pair `(outcome, state)` where `outcome` is the** + +measurement outcome string label, and `state` is the collapsed post-measurement stabilizer state for the corresponding outcome. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### probabilities + + + +`probabilities(qargs=None, decimals=None)` + +Return the subsystem measurement probability vector. + +Measurement probabilities are with respect to measurement in the computation (diagonal) basis. + +**Parameters** + +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None). +* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +The Numpy vector array of probabilities. + +**Return type** + +np.array + +### probabilities\_dict + + + +`probabilities_dict(qargs=None, decimals=None)` + +Return the subsystem measurement probability dictionary. + +Measurement probabilities are with respect to measurement in the computation (diagonal) basis. + +This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished. + +**Parameters** + +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None). +* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +The measurement probabilities in dict (ket) form. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### purity + + + +`purity()` + +Return the purity of the quantum state, which equals to 1, since it is always a pure state. + +**Returns** + +the purity (should equal 1). + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input is not a StabilizerState. + +### reset + + + +`reset(qargs=None)` + +Reset state or subsystems to the 0-state. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None). + +**Returns** + +the reset state. + +**Return type** + +[StabilizerState](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState") + +**Additional Information:** + +If all subsystems are reset this will return the ground state on all subsystems. If only some subsystems are reset this function will perform a measurement on those subsystems and evolve the subsystems so that the collapsed post-measurement states are rotated to the 0-state. The RNG seed for this sampling can be set using the [`seed()`](#qiskit.quantum_info.StabilizerState.seed "qiskit.quantum_info.StabilizerState.seed") method. + +### sample\_counts + + + +`sample_counts(shots, qargs=None)` + +Sample a dict of qubit measurement outcomes in the computational basis. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of samples to generate. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +sampled counts dictionary. + +**Return type** + +[Counts](qiskit.result.Counts "qiskit.result.Counts") + +Additional Information: + +> This function *samples* measurement outcomes using the measure [`probabilities()`](#qiskit.quantum_info.StabilizerState.probabilities "qiskit.quantum_info.StabilizerState.probabilities") for the current state and qargs. It does not actually implement the measurement so the current state is not modified. +> +> The seed for random number generator used for sampling can be set to a fixed value by using the stats [`seed()`](#qiskit.quantum_info.StabilizerState.seed "qiskit.quantum_info.StabilizerState.seed") method. + +### sample\_memory + + + +`sample_memory(shots, qargs=None)` + +Sample a list of qubit measurement outcomes in the computational basis. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of samples to generate. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +list of sampled counts if the order sampled. + +**Return type** + +np.array + +Additional Information: + +> This function implements the measurement [`measure()`](#qiskit.quantum_info.StabilizerState.measure "qiskit.quantum_info.StabilizerState.measure") method. +> +> The seed for random number generator used for sampling can be set to a fixed value by using the stats [`seed()`](#qiskit.quantum_info.StabilizerState.seed "qiskit.quantum_info.StabilizerState.seed") method. + +### seed + + + +`seed(value=None)` + +Set the seed for the quantum state RNG. + +### tensor + + + +`tensor(other)` + +Return the tensor product stabilizer state self ⊗ other. + +**Parameters** + +**other** ([*StabilizerState*](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState")) – a stabilizer state object. + +**Returns** + +the tensor product operator self ⊗ other. + +**Return type** + +[StabilizerState](#qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a StabilizerState. + +### to\_operator + + + +`to_operator()` + +Convert state to matrix operator class + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### trace + + + +`trace()` + +Return the trace of the stabilizer state as a density matrix, which equals to 1, since it is always a pure state. + +**Returns** + +the trace (should equal 1). + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input is not a StabilizerState. + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Statevector.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Statevector.md new file mode 100644 index 00000000000..d2fbdbb6bc8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Statevector.md @@ -0,0 +1,732 @@ +--- +title: Statevector +description: API reference for qiskit.quantum_info.Statevector +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Statevector +--- + +# Statevector + + + +`qiskit.quantum_info.Statevector(data, dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/statevector.py "view source code") + +Bases: `QuantumState`, `TolerancesMixin` + +Statevector class + +Initialize a statevector object. + +**Parameters** + +* **or** (*data (np.array or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*Statevector*](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – qiskit.circuit.Instruction): Data from which the statevector can be constructed. This can be either a complex vector, another statevector, a `Operator` with only one column or a `QuantumCircuit` or `Instruction`. If the data is a circuit or instruction, the statevector is constructed by assuming that all qubits are initialized to the zero state. +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Optional. The subsystem dimension of the state (See additional information). + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not valid. + +**Additional Information:** + +The `dims` kwarg can be None, an integer, or an iterable of integers. + +* `Iterable` – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list. +* `Int` or `None` – the length of the input vector specifies the total dimension of the density matrix. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return data. + + + +### dim + +Return total state dimension. + + + +### num\_qubits + +Return the number of qubits if a N-qubit state or None otherwise. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### conjugate + + + +`conjugate()` + +Return the conjugate of the operator. + +**Return type** + +[*Statevector*](#qiskit.quantum_info.Statevector "qiskit.quantum_info.states.statevector.Statevector") + +### copy + + + +`copy()` + +Make a copy of current operator. + +### dims + + + +`dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### draw + + + +`draw(output=None, **drawer_args)` + +Return a visualization of the Statevector. + +**repr**: ASCII TextMatrix of the state’s `__repr__`. + +**text**: ASCII TextMatrix that can be printed in the console. + +**latex**: An IPython Latex object for displaying in Jupyter Notebooks. + +**latex\_source**: Raw, uncompiled ASCII source to generate array using LaTeX. + +**qsphere**: Matplotlib figure, rendering of statevector using plot\_state\_qsphere(). + +**hinton**: Matplotlib figure, rendering of statevector using plot\_state\_hinton(). + +**bloch**: Matplotlib figure, rendering of statevector using plot\_bloch\_multivector(). + +**city**: Matplotlib figure, rendering of statevector using plot\_state\_city(). + +**paulivec**: Matplotlib figure, rendering of statevector using plot\_state\_paulivec(). + +**Parameters** + +* **output** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Select the output method to use for drawing the state. Valid choices are repr, text, latex, latex\_source, qsphere, hinton, bloch, city, or paulivec. Default is repr. Default can be changed by adding the line `state_drawer = ` to `~/.qiskit/settings.conf` under `[default]`. +* **drawer\_args** – Arguments to be passed directly to the relevant drawing function or constructor (TextMatrix(), array\_to\_latex(), plot\_state\_qsphere(), plot\_state\_hinton() or plot\_bloch\_multivector()). See the relevant function under qiskit.visualization for that function’s documentation. + +**Returns** + +`matplotlib.Figure` or [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") or `TextMatrix` or `IPython.display.Latex`: Drawing of the Statevector. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – when an invalid output method is selected. + +**Examples** + +Plot one of the Bell states + +```python +from numpy import sqrt +from qiskit.quantum_info import Statevector +sv=Statevector([1/sqrt(2), 0, 0, -1/sqrt(2)]) +sv.draw(output='hinton') +``` + +![../\_images/qiskit-quantum\_info-Statevector-1.png](/images/api/qiskit/0.46/qiskit-quantum_info-Statevector-1.png) + +### equiv + + + +`equiv(other, rtol=None, atol=None)` + +Return True if other is equivalent as a statevector up to global phase. + + + If other is not a Statevector, but can be used to initialize a statevector object, this will check that Statevector(other) is equivalent to the current statevector up to global phase. + + +**Parameters** + +* **other** ([*Statevector*](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – an object from which a `Statevector` can be constructed. +* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – relative tolerance value for comparison. +* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – absolute tolerance value for comparison. + +**Returns** + +True if statevectors are equivalent up to global phase. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### evolve + + + +`evolve(other, qargs=None)` + +Evolve a quantum state by the operator. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") *|*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *|*[*circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – The operator to evolve by. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list of Statevector subsystem positions to apply the operator on. + +**Returns** + +the output quantum state. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the operator dimension does not match the specified Statevector subsystem dimensions. + +### expand + + + +`expand(other)` + +Return the tensor product state other ⊗ self. + +**Parameters** + +**other** ([*Statevector*](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – a quantum state object. + +**Returns** + +the tensor product state other ⊗ self. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state. + +### expectation\_value + + + +`expectation_value(oper, qargs=None)` + +Compute the expectation value of an operator. + +**Parameters** + +* **oper** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator to evaluate expval of. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to apply operator on. + +**Returns** + +the expectation value. + +**Return type** + +[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)") + +### from\_instruction + + + +`classmethod from_instruction(instruction)` + +Return the output statevector of an instruction. + +The statevector is initialized in the state $|{0,\ldots,0}\rangle$ of the same number of qubits as the input instruction or circuit, evolved by the input instruction, and the output statevector returned. + +**Parameters** + +**instruction** ([*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – instruction or circuit + +**Returns** + +The final statevector. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instruction contains invalid instructions for the statevector simulation. + +### from\_int + + + +`static from_int(i, dims)` + +Return a computational basis statevector. + +**Parameters** + +* **i** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the basis state element. +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The subsystem dimensions of the statevector (See additional information). + +**Returns** + +The computational basis state $|i\rangle$. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Additional Information:** + +The `dims` kwarg can be an integer or an iterable of integers. + +* `Iterable` – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list. +* `Int` – the integer specifies the total dimension of the state. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem. + +### from\_label + + + +`classmethod from_label(label)` + +Return a tensor product of Pauli X,Y,Z eigenstates. + +| Label | Statevector | +| ----- | ------------------------------- | +| `"0"` | $[1, 0]$ | +| `"1"` | $[0, 1]$ | +| `"+"` | $[1 / \sqrt{2}, 1 / \sqrt{2}]$ | +| `"-"` | $[1 / \sqrt{2}, -1 / \sqrt{2}]$ | +| `"r"` | $[1 / \sqrt{2}, i / \sqrt{2}]$ | +| `"l"` | $[1 / \sqrt{2}, -i / \sqrt{2}]$ | + +**Parameters** + +**label** (*string*) – a eigenstate string ket label (see table for allowed values). + +**Returns** + +The N-qubit basis state density matrix. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the label contains invalid characters, or the length of the label is larger than an explicitly specified num\_qubits. + +### inner + + + +`inner(other)` + +Return the inner product of self and other as $\langle self| other \rangle$. + +**Parameters** + +**other** ([*Statevector*](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – a quantum state object. + +**Returns** + +the inner product of self and other, $\langle self| other \rangle$. + +**Return type** + +np.complex128 + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state or has different dimension. + +### is\_valid + + + +`is_valid(atol=None, rtol=None)` + +Return True if a Statevector has norm 1. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### measure + + + +`measure(qargs=None)` + +Measure subsystems and return outcome and post-measure state. + +Note that this function uses the QuantumStates internal random number generator for sampling the measurement outcome. The RNG seed can be set using the [`seed()`](#qiskit.quantum_info.Statevector.seed "qiskit.quantum_info.Statevector.seed") method. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +**the pair `(outcome, state)` where `outcome` is the** + +measurement outcome string label, and `state` is the collapsed post-measurement state for the corresponding outcome. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### probabilities + + + +`probabilities(qargs=None, decimals=None)` + +Return the subsystem measurement probability vector. + +Measurement probabilities are with respect to measurement in the computation (diagonal) basis. + +**Parameters** + +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None). +* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +The Numpy vector array of probabilities. + +**Return type** + +np.array + +**Examples** + +Consider a 2-qubit product state $|\psi\rangle=|+\rangle\otimes|0\rangle$. + +```python +from qiskit.quantum_info import Statevector + +psi = Statevector.from_label('+0') + +# Probabilities for measuring both qubits +probs = psi.probabilities() +print('probs: {}'.format(probs)) + +# Probabilities for measuring only qubit-0 +probs_qubit_0 = psi.probabilities([0]) +print('Qubit-0 probs: {}'.format(probs_qubit_0)) + +# Probabilities for measuring only qubit-1 +probs_qubit_1 = psi.probabilities([1]) +print('Qubit-1 probs: {}'.format(probs_qubit_1)) +``` + +```python +probs: [0.5 0. 0.5 0. ] +Qubit-0 probs: [1. 0.] +Qubit-1 probs: [0.5 0.5] +``` + +We can also permute the order of qubits in the `qargs` list to change the qubit position in the probabilities output + +```python +from qiskit.quantum_info import Statevector + +psi = Statevector.from_label('+0') + +# Probabilities for measuring both qubits +probs = psi.probabilities([0, 1]) +print('probs: {}'.format(probs)) + +# Probabilities for measuring both qubits +# but swapping qubits 0 and 1 in output +probs_swapped = psi.probabilities([1, 0]) +print('Swapped probs: {}'.format(probs_swapped)) +``` + +```python +probs: [0.5 0. 0.5 0. ] +Swapped probs: [0.5 0.5 0. 0. ] +``` + +### probabilities\_dict + + + +`probabilities_dict(qargs=None, decimals=None)` + +Return the subsystem measurement probability dictionary. + +Measurement probabilities are with respect to measurement in the computation (diagonal) basis. + +This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished. + +**Parameters** + +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None). +* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +The measurement probabilities in dict (ket) form. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### purity + + + +`purity()` + +Return the purity of the quantum state. + +**Return type** + +*float64* + +### reset + + + +`reset(qargs=None)` + +Reset state or subsystems to the 0-state. + +**Parameters** + +**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None). + +**Returns** + +the reset state. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Additional Information:** + +If all subsystems are reset this will return the ground state on all subsystems. If only a some subsystems are reset this function will perform a measurement on those subsystems and evolve the subsystems so that the collapsed post-measurement states are rotated to the 0-state. The RNG seed for this sampling can be set using the [`seed()`](#qiskit.quantum_info.Statevector.seed "qiskit.quantum_info.Statevector.seed") method. + +### reverse\_qargs + + + +`reverse_qargs()` + +Return a Statevector with reversed subsystem ordering. + +For a tensor product state this is equivalent to reversing the order of tensor product subsystems. For a statevector $|\psi \rangle = |\psi_{n-1} \rangle \otimes ... \otimes |\psi_0 \rangle$ the returned statevector will be $|\psi_{0} \rangle \otimes ... \otimes |\psi_{n-1} \rangle$. + +**Returns** + +the Statevector with reversed subsystem order. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +### sample\_counts + + + +`sample_counts(shots, qargs=None)` + +Sample a dict of qubit measurement outcomes in the computational basis. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of samples to generate. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +sampled counts dictionary. + +**Return type** + +[Counts](qiskit.result.Counts "qiskit.result.Counts") + +Additional Information: + +> This function *samples* measurement outcomes using the measure [`probabilities()`](#qiskit.quantum_info.Statevector.probabilities "qiskit.quantum_info.Statevector.probabilities") for the current state and qargs. It does not actually implement the measurement so the current state is not modified. +> +> The seed for random number generator used for sampling can be set to a fixed value by using the stats [`seed()`](#qiskit.quantum_info.Statevector.seed "qiskit.quantum_info.Statevector.seed") method. + +### sample\_memory + + + +`sample_memory(shots, qargs=None)` + +Sample a list of qubit measurement outcomes in the computational basis. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of samples to generate. +* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None). + +**Returns** + +list of sampled counts if the order sampled. + +**Return type** + +np.array + +Additional Information: + +> This function *samples* measurement outcomes using the measure [`probabilities()`](#qiskit.quantum_info.Statevector.probabilities "qiskit.quantum_info.Statevector.probabilities") for the current state and qargs. It does not actually implement the measurement so the current state is not modified. +> +> The seed for random number generator used for sampling can be set to a fixed value by using the stats [`seed()`](#qiskit.quantum_info.Statevector.seed "qiskit.quantum_info.Statevector.seed") method. + +### seed + + + +`seed(value=None)` + +Set the seed for the quantum state RNG. + +### tensor + + + +`tensor(other)` + +Return the tensor product state self ⊗ other. + +**Parameters** + +**other** ([*Statevector*](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")) – a quantum state object. + +**Returns** + +the tensor product operator self ⊗ other. + +**Return type** + +[Statevector](#qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state. + +### to\_dict + + + +`to_dict(decimals=None)` + +Convert the statevector to dictionary form. + +This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished. + +**Parameters** + +**decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimal places to round values. If None no rounding is done (Default: None). + +**Returns** + +the dictionary form of the Statevector. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Example** + +The ket-form of a 2-qubit statevector $|\psi\rangle = |-\rangle\otimes |0\rangle$ + +```python +from qiskit.quantum_info import Statevector + +psi = Statevector.from_label('-0') +print(psi.to_dict()) +``` + +```python +{'00': (0.7071067811865475+0j), '10': (-0.7071067811865475+0j)} +``` + +For non-qubit subsystems the integer range can go from 0 to 9. For example in a qutrit system + +```python +import numpy as np +from qiskit.quantum_info import Statevector + +vec = np.zeros(9) +vec[0] = 1 / np.sqrt(2) +vec[-1] = 1 / np.sqrt(2) +psi = Statevector(vec, dims=(3, 3)) +print(psi.to_dict()) +``` + +```python +{'00': (0.7071067811865475+0j), '22': (0.7071067811865475+0j)} +``` + +For large subsystem dimensions delimiters are required. The following example is for a 20-dimensional system consisting of a qubit and 10-dimensional qudit. + +```python +import numpy as np +from qiskit.quantum_info import Statevector + +vec = np.zeros(2 * 10) +vec[0] = 1 / np.sqrt(2) +vec[-1] = 1 / np.sqrt(2) +psi = Statevector(vec, dims=(2, 10)) +print(psi.to_dict()) +``` + +```python +{'00': (0.7071067811865475+0j), '91': (0.7071067811865475+0j)} +``` + +### to\_operator + + + +`to_operator()` + +Convert state to a rank-1 projector operator + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### trace + + + +`trace()` + +Return the trace of the quantum state as a density matrix. + +**Return type** + +*float64* + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Stinespring.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Stinespring.md new file mode 100644 index 00000000000..b4f3bdcff37 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Stinespring.md @@ -0,0 +1,399 @@ +--- +title: Stinespring +description: API reference for qiskit.quantum_info.Stinespring +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Stinespring +--- + +# Stinespring + + + +`qiskit.quantum_info.Stinespring(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/channel/stinespring.py "view source code") + +Bases: `QuantumChannel` + +Stinespring representation of a quantum channel. + +The Stinespring representation of a quantum channel $\mathcal{E}$ is a rectangular matrix $A$ such that the evolution of a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ is given by + +$$ +\mathcal{E}(ρ) = \mbox{Tr}_2\left[A ρ A^\dagger\right] +$$ + +where $\mbox{Tr}_2$ is the [`partial_trace()`](quantum_info#qiskit.quantum_info.partial_trace "qiskit.quantum_info.partial_trace") over subsystem 2. + +A general operator map $\mathcal{G}$ can also be written using the generalized Stinespring representation which is given by two matrices $A$, $B$ such that + +$$ +\mathcal{G}(ρ) = \mbox{Tr}_2\left[A ρ B^\dagger\right] +$$ + +See reference \[1] for further details. + +**References** + +1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015). [arXiv:1111.6950 \[quant-ph\]](https://arxiv.org/abs/1111.6950) + +Initialize a quantum channel Stinespring operator. + +**Parameters** + +* **or** (*data (*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Instruction or BaseOperator or matrix): data to initialize superoperator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input subsystem dimensions. \[Default: None] +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the output subsystem dimensions. \[Default: None] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data cannot be initialized as a a list of Kraus matrices. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. This can fail for the Stinespring operator if the output dimension cannot be automatically determined. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint quantum channel. + + + This is equivalent to the matrix Hermitian conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the adjoint channel $\mathcal{{E}}^\dagger$ is $S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger$. + + +**Return type** + +*Self* + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another Stinespring. + +**Parameters** + +* **other** ([*Stinespring*](#qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring")) – a Stinespring object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed Stinespring. + +**Return type** + +[Stinespring](#qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.Stinespring.dot "qiskit.quantum_info.Stinespring.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.Stinespring.dot "qiskit.quantum_info.Stinespring.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate quantum channel. + + + This is equivalent to the matrix complex conjugate in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the conjugate channel $\overline{{\mathcal{{E}}}}$ is $S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}$. + + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another Stinespring. + +**Parameters** + +**other** ([*Stinespring*](#qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring")) – a Stinespring object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current Stinespring, and $b$ is the other Stinespring. + +**Return type** + +[Stinespring](#qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_cp + + + +`is_cp(atol=None, rtol=None)` + +Test if Choi-matrix is completely-positive (CP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_cptp + + + +`is_cptp(atol=None, rtol=None)` + +Return True if completely-positive trace-preserving. + +### is\_tp + + + +`is_tp(atol=None, rtol=None)` + +Test if a channel is trace-preserving (TP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if QuantumChannel is a unitary channel. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the quantum channel. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power exponent. + +**Returns** + +the channel $\mathcal{{E}} ^n$. + +**Return type** + +[SuperOp](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the SuperOp are not equal. + + + For non-positive or non-integer exponents the power is defined as the matrix power of the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{{E}}$, the SuperOp of the powered channel $\mathcal{{E}}^\n$ is $S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n$. + + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another Stinespring. + +**Parameters** + +**other** ([*Stinespring*](#qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring")) – a Stinespring object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current Stinespring, and $b$ is the other Stinespring. + +**Return type** + +[Stinespring](#qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a Kraus or UnitaryGate circuit instruction. + +If the channel is unitary it will be added as a unitary gate, otherwise it will be added as a kraus simulator instruction. + +**Returns** + +A kraus instruction for the channel. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit CPTP quantum channel. + +### to\_operator + + + +`to_operator()` + +Try to convert channel to a unitary representation Operator. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose quantum channel. + + + This is equivalent to the matrix transpose in the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation, ie. for a channel $\mathcal{E}$, the SuperOp of the transpose channel $\mathcal{{E}}^T$ is $S_{mathcal{E}^T} = S_{\mathcal{E}}^T$. + + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.SuperOp.md b/docs/api/qiskit/0.46/qiskit.quantum_info.SuperOp.md new file mode 100644 index 00000000000..f52c92569a8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.SuperOp.md @@ -0,0 +1,395 @@ +--- +title: SuperOp +description: API reference for qiskit.quantum_info.SuperOp +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.SuperOp +--- + +# SuperOp + + + +`qiskit.quantum_info.SuperOp(data, input_dims=None, output_dims=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/channel/superop.py "view source code") + +Bases: `QuantumChannel` + +Superoperator representation of a quantum channel. + +The Superoperator representation of a quantum channel $\mathcal{E}$ is a matrix $S$ such that the evolution of a [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") $\rho$ is given by + +$$ +|\mathcal{E}(\rho)\rangle\!\rangle = S |\rho\rangle\!\rangle +$$ + +where the double-ket notation $|A\rangle\!\rangle$ denotes a vector formed by stacking the columns of the matrix $A$ *(column-vectorization)*. + +See reference \[1] for further details. + +**References** + +1. C.J. Wood, J.D. Biamonte, D.G. Cory, *Tensor networks and graphical calculus for open quantum systems*, Quant. Inf. Comp. 15, 0579-0811 (2015). [arXiv:1111.6950 \[quant-ph\]](https://arxiv.org/abs/1111.6950) + +Initialize a quantum channel Superoperator operator. + +**Parameters** + +* **or** (*data (*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Instruction or BaseOperator or matrix): data to initialize superoperator. +* **input\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input subsystem dimensions. \[Default: None] +* **output\_dims** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the output subsystem dimensions. \[Default: None] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data cannot be initialized as a superoperator. + +**Additional Information:** + +If the input or output dimensions are None, they will be automatically determined from the input data. If the input data is a Numpy array of shape (4\*\*N, 4\*\*N) qubit systems will be used. If the input operator is not an N-qubit operator, it will assign a single subsystem with dimension specified by the shape of the input. + +## Attributes + + + +### atol + +`= 1e-08` + + + +### data + +Return data. + + + +### dim + +Return tuple (input\_shape, output\_shape). + + + +### num\_qubits + +Return the number of qubits if a N-qubit operator or None otherwise. + + + +### qargs + +Return the qargs for the operator. + + + +### rtol + +`= 1e-05` + + + +### settings + +Return settings. + +## Methods + +### adjoint + + + +`adjoint()` + +Return the adjoint quantum channel. + + + This is equivalent to the matrix Hermitian conjugate in the [`SuperOp`](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the adjoint channel $\mathcal{{E}}^\dagger$ is $S_{\mathcal{E}^\dagger} = S_{\mathcal{E}}^\dagger$. + + +### compose + + + +`compose(other, qargs=None, front=False)` + +Return the operator composition with another SuperOp. + +**Parameters** + +* **other** ([*SuperOp*](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp")) – a SuperOp object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). +* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True compose using right operator multiplication, instead of left multiplication \[default: False]. + +**Returns** + +The composed SuperOp. + +**Return type** + +[SuperOp](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other cannot be converted to an operator, or has incompatible dimensions for specified subsystems. + + + Composition (`&`) by default is defined as left matrix multiplication for matrix operators, while `@` (equivalent to [`dot()`](#qiskit.quantum_info.SuperOp.dot "qiskit.quantum_info.SuperOp.dot")) is defined as right matrix multiplication. That is that `A & B == A.compose(B)` is equivalent to `B @ A == B.dot(A)` when `A` and `B` are of the same type. + + Setting the `front=True` kwarg changes this to right matrix multiplication and is equivalent to the [`dot()`](#qiskit.quantum_info.SuperOp.dot "qiskit.quantum_info.SuperOp.dot") method `A.dot(B) == A.compose(B, front=True)`. + + +### conjugate + + + +`conjugate()` + +Return the conjugate quantum channel. + + + This is equivalent to the matrix complex conjugate in the [`SuperOp`](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{E}$, the SuperOp of the conjugate channel $\overline{{\mathcal{{E}}}}$ is $S_{\overline{\mathcal{E}^\dagger}} = \overline{S_{\mathcal{E}}}$. + + +### copy + + + +`copy()` + +Make a deep copy of current operator. + +### dot + + + +`dot(other, qargs=None)` + +Return the right multiplied operator self \* other. + +**Parameters** + +* **other** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator object. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None). + +**Returns** + +The right matrix multiplied Operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + + + The dot product can be obtained using the `@` binary operator. Hence `a.dot(b)` is equivalent to `a @ b`. + + +### expand + + + +`expand(other)` + +Return the reverse-order tensor product with another SuperOp. + +**Parameters** + +**other** ([*SuperOp*](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp")) – a SuperOp object. + +**Returns** + +**the tensor product $b \otimes a$, where $a$** + +is the current SuperOp, and $b$ is the other SuperOp. + +**Return type** + +[SuperOp](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +### input\_dims + + + +`input_dims(qargs=None)` + +Return tuple of input dimension for specified subsystems. + +### is\_cp + + + +`is_cp(atol=None, rtol=None)` + +Test if Choi-matrix is completely-positive (CP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_cptp + + + +`is_cptp(atol=None, rtol=None)` + +Return True if completely-positive trace-preserving (CPTP). + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_tp + + + +`is_tp(atol=None, rtol=None)` + +Test if a channel is trace-preserving (TP) + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### is\_unitary + + + +`is_unitary(atol=None, rtol=None)` + +Return True if QuantumChannel is a unitary channel. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### output\_dims + + + +`output_dims(qargs=None)` + +Return tuple of output dimension for specified subsystems. + +### power + + + +`power(n)` + +Return the power of the quantum channel. + +**Parameters** + +**n** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – the power exponent. + +**Returns** + +the channel $\mathcal{{E}} ^n$. + +**Return type** + +[SuperOp](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input and output dimensions of the SuperOp are not equal. + + + For non-positive or non-integer exponents the power is defined as the matrix power of the [`SuperOp`](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation ie. for a channel $\mathcal{{E}}$, the SuperOp of the powered channel $\mathcal{{E}}^\n$ is $S_{{\mathcal{{E}}^n}} = S_{{\mathcal{{E}}}}^n$. + + +### reshape + + + +`reshape(input_dims=None, output_dims=None, num_qubits=None)` + +Return a shallow copy with reshaped input and output subsystem dimensions. + +**Parameters** + +* **input\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem input dimensions. If None the original input dims will be preserved \[Default: None]. +* **output\_dims** (*None or* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – new subsystem output dimensions. If None the original output dims will be preserved \[Default: None]. +* **num\_qubits** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – reshape to an N-qubit operator \[Default: None]. + +**Returns** + +returns self with reshaped input and output dimensions. + +**Return type** + +BaseOperator + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if combined size of all subsystem input dimension or subsystem output dimensions is not constant. + +### tensor + + + +`tensor(other)` + +Return the tensor product with another SuperOp. + +**Parameters** + +**other** ([*SuperOp*](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp")) – a SuperOp object. + +**Returns** + +**the tensor product $a \otimes b$, where $a$** + +is the current SuperOp, and $b$ is the other SuperOp. + +**Return type** + +[SuperOp](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") + + + The tensor product can be obtained using the `^` binary operator. Hence `a.tensor(b)` is equivalent to `a ^ b`. + + +### to\_instruction + + + +`to_instruction()` + +Convert to a Kraus or UnitaryGate circuit instruction. + +If the channel is unitary it will be added as a unitary gate, otherwise it will be added as a kraus simulator instruction. + +**Returns** + +A kraus instruction for the channel. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input data is not an N-qubit CPTP quantum channel. + +### to\_operator + + + +`to_operator()` + +Try to convert channel to a unitary representation Operator. + +**Return type** + +[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator") + +### transpose + + + +`transpose()` + +Return the transpose quantum channel. + + + This is equivalent to the matrix transpose in the [`SuperOp`](#qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") representation, ie. for a channel $\mathcal{E}$, the SuperOp of the transpose channel $\mathcal{{E}}^T$ is $S_{mathcal{E}^T} = S_{\mathcal{E}}^T$. + + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.Z2Symmetries.md b/docs/api/qiskit/0.46/qiskit.quantum_info.Z2Symmetries.md new file mode 100644 index 00000000000..c409ad4063e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.Z2Symmetries.md @@ -0,0 +1,192 @@ +--- +title: Z2Symmetries +description: API reference for qiskit.quantum_info.Z2Symmetries +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.quantum_info.Z2Symmetries +--- + +# Z2Symmetries + + + +`qiskit.quantum_info.Z2Symmetries(symmetries, sq_paulis, sq_list, tapering_values=None, *, tol=1e-14)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/analysis/z2_symmetries.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +The \$Z\_2\$ symmetry converter identifies symmetries from the problem hamiltonian and uses them to provide a tapered - more efficient - representation of operators as Paulis for this problem. For each identified symmetry, one qubit can be eliminated in the Pauli representation at the cost of having to test two symmetry sectors (for the two possible eigenvalues - tapering values - of the symmetry). In certain problems such as the finding of the main operator’s ground state, one can a priori identify the symmetry sector of the solution and thus effectively reduce the computational overhead. + +The following attributes can be read and updated once the `Z2Symmetries` object has been constructed. + + + +### tapering\_values + +Values determining the sector. + +**Type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] or None + + + +### tol + +The tolerance threshold for ignoring real and complex parts of a coefficient. + +**Type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**References** + +**\[1]: Bravyi, S., et al, “Tapering off qubits to simulate fermionic Hamiltonians”** + +[arXiv:1701.08213](https://arxiv.org/abs/1701.08213) + +**Parameters** + +* **symmetries** (*Iterable\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")*]*) – Object representing the list of \$Z\_2\$ symmetries. These correspond to the generators of the symmetry group \$langle tau\_1, tau\_2dots rangle>\$. +* **sq\_paulis** (*Iterable\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")*]*) – Object representing the list of single-qubit Pauli \$sigma^x\_\{q(i)}\$ anti-commuting with the symmetry \$tau\_i\$ and commuting with all the other symmetries \$tau\_\{jneq i}\$. These operators are used to construct the unitary Clifford operators. +* **sq\_list** (*Iterable\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – The list of indices \$q(i)\$ of the single-qubit Pauli operators used to build the Clifford operators. +* **tapering\_values** (*Iterable\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – List of eigenvalues determining the symmetry sector for each symmetry. +* **tol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Tolerance threshold for ignoring real and complex parts of a coefficient. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Invalid paulis. The lists of symmetries, single-qubit paulis support paulis and tapering values must be of equal length. This length is the number of applied symmetries and translates directly to the number of eliminated qubits. + +## Attributes + + + +### cliffords + +Get clifford operators, built based on symmetries and single-qubit X. + +**Returns** + +A list of unitaries used to diagonalize the Hamiltonian. + + + +### settings + +Return operator settings. + + + +### sq\_list + +Return sq list. + + + +### sq\_paulis + +Return sq paulis. + + + +### symmetries + +Return symmetries. + +## Methods + +### convert\_clifford + + + +`convert_clifford(operator)` + +This method operates the first part of the tapering. It converts the operator by composing it with the clifford unitaries defined in the current symmetry. + +**Parameters** + +**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")) – The to-be-tapered operator. + +**Returns** + +`SparsePauliOp` corresponding to the converted operator. + +**Return type** + +[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp") + +### find\_z2\_symmetries + + + +`classmethod find_z2_symmetries(operator)` + +Finds Z2 Pauli-type symmetries of a [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"). + +**Returns** + +A `Z2Symmetries` instance. + +**Return type** + +[*Z2Symmetries*](#qiskit.quantum_info.Z2Symmetries "qiskit.quantum_info.analysis.z2_symmetries.Z2Symmetries") + +### is\_empty + + + +`is_empty()` + +Check the z2\_symmetries is empty or not. + +**Returns** + +Empty or not. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### taper + + + +`taper(operator)` + +Taper an operator based on the z2\_symmetries info and sector defined by tapering\_values. Returns operator if the symmetry object is empty. + +The tapering is a two-step algorithm which first converts the operator into a [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") with same eigenvalues but where some qubits are only acted upon with the Pauli operators I or X. The number M of these redundant qubits is equal to the number M of identified symmetries. + +The second step of the reduction consists in replacing these qubits with the possible eigenvalues of the corresponding Pauli X, giving 2^M new operators with M less qubits. If an eigenvalue sector was previously identified for the solution, then this reduces to 1 new operator with M less qubits. + +**Parameters** + +**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")) – The to-be-tapered operator. + +**Returns** + +\[[`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")]; otherwise, [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"). + +**Return type** + +If tapering\_values is None + +### taper\_clifford + + + +`taper_clifford(operator)` + +Operate the second part of the tapering. This function assumes that the input operators have already been transformed using [`convert_clifford()`](#qiskit.quantum_info.Z2Symmetries.convert_clifford "qiskit.quantum_info.Z2Symmetries.convert_clifford"). The redundant qubits due to the symmetries are dropped and replaced by their two possible eigenvalues. + +**Parameters** + +**operator** ([*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")) – Partially tapered operator resulting from a call to [`convert_clifford()`](#qiskit.quantum_info.Z2Symmetries.convert_clifford "qiskit.quantum_info.Z2Symmetries.convert_clifford"). + +**Returns** + +\[[`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")]; otherwise, [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"). + +**Return type** + +If tapering\_values is None + diff --git a/docs/api/qiskit/0.46/qiskit.quantum_info.pauli_basis.md b/docs/api/qiskit/0.46/qiskit.quantum_info.pauli_basis.md new file mode 100644 index 00000000000..7f4330f3aea --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.quantum_info.pauli_basis.md @@ -0,0 +1,31 @@ +--- +title: pauli_basis +description: API reference for qiskit.quantum_info.pauli_basis +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.quantum_info.pauli_basis +--- + + + +# qiskit.quantum\_info.pauli\_basis + + + +`qiskit.quantum_info.pauli_basis(num_qubits, weight=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/pauli_utils.py "view source code") + +Return the ordered PauliList for the n-qubit Pauli basis. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits +* **weight** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True optionally return the basis sorted by Pauli weight rather than lexicographic order (Default: False) + +**Returns** + +the Paulis for the basis + +**Return type** + +[PauliList](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + diff --git a/docs/api/qiskit/0.46/qiskit.result.BaseReadoutMitigator.md b/docs/api/qiskit/0.46/qiskit.result.BaseReadoutMitigator.md new file mode 100644 index 00000000000..e10e4871916 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.BaseReadoutMitigator.md @@ -0,0 +1,69 @@ +--- +title: BaseReadoutMitigator +description: API reference for qiskit.result.BaseReadoutMitigator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.BaseReadoutMitigator +--- + +# BaseReadoutMitigator + + + +`qiskit.result.BaseReadoutMitigator`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/mitigation/base_readout_mitigator.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Base readout error mitigator class. + +## Methods + +### expectation\_value + + + +`abstract expectation_value(data, diagonal, qubits=None, clbits=None, shots=None)` + +Calculate the expectation value of a diagonal Hermitian operator. + +**Parameters** + +* **data** ([*Counts*](qiskit.result.Counts "qiskit.result.counts.Counts")) – Counts object to be mitigated. +* **diagonal** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – the diagonal operator. This may either be specified as a string containing I,Z,0,1 characters, or as a real valued 1D array\_like object supplying the full diagonal, or as a dictionary, or as Callable. +* **qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – the physical qubits measured to obtain the counts clbits. If None these are assumed to be qubits \[0, …, N-1] for N-bit counts. +* **clbits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, marginalize counts to just these bits. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional, the total number of shots, if None shots will be calculated as the sum of all counts. + +**Returns** + +The mean and an upper bound of the standard deviation of operator expectation value calculated from the current counts. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] + +### quasi\_probabilities + + + +`abstract quasi_probabilities(data, qubits=None, clbits=None, shots=None)` + +Convert counts to a dictionary of quasi-probabilities + +**Parameters** + +* **data** ([*Counts*](qiskit.result.Counts "qiskit.result.counts.Counts")) – Counts to be mitigated. +* **qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – the physical qubits measured to obtain the counts clbits. If None these are assumed to be qubits \[0, …, N-1] for N-bit counts. +* **clbits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, marginalize counts to just these bits. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional, the total number of shots, if None shots will be calculated as the sum of all counts. + +**Returns** + +**A dictionary containing pairs of \[output, mean] where “output”** + +is the key in the dictionaries, which is the length-N bitstring of a measured standard basis state, and “mean” is the mean of non-zero quasi-probability estimates. + +**Return type** + +[QuasiDistribution](qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution") + diff --git a/docs/api/qiskit/0.46/qiskit.result.CorrelatedReadoutMitigator.md b/docs/api/qiskit/0.46/qiskit.result.CorrelatedReadoutMitigator.md new file mode 100644 index 00000000000..9f9c36d2f35 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.CorrelatedReadoutMitigator.md @@ -0,0 +1,166 @@ +--- +title: CorrelatedReadoutMitigator +description: API reference for qiskit.result.CorrelatedReadoutMitigator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.CorrelatedReadoutMitigator +--- + +# CorrelatedReadoutMitigator + + + +`qiskit.result.CorrelatedReadoutMitigator(assignment_matrix, qubits=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/mitigation/correlated_readout_mitigator.py "view source code") + +Bases: [`BaseReadoutMitigator`](qiskit.result.BaseReadoutMitigator "qiskit.result.mitigation.base_readout_mitigator.BaseReadoutMitigator") + +N-qubit readout error mitigator. + +Mitigates [`expectation_value()`](#qiskit.result.CorrelatedReadoutMitigator.expectation_value "qiskit.result.CorrelatedReadoutMitigator.expectation_value") and [`quasi_probabilities()`](#qiskit.result.CorrelatedReadoutMitigator.quasi_probabilities "qiskit.result.CorrelatedReadoutMitigator.quasi_probabilities"). The mitigation\_matrix should be calibrated using qiskit experiments. This mitigation method should be used in case the readout errors of the qubits are assumed to be correlated. The mitigation\_matrix of *N* qubits is of size $2^N x 2^N$ so the mitigation complexity is $O(4^N)$. + +Initialize a CorrelatedReadoutMitigator + +**Parameters** + +* **assignment\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – readout error assignment matrix. +* **qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, the measured physical qubits for mitigation. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – matrix size does not agree with number of qubits + +## Attributes + + + +### qubits + +The device qubits for this mitigator + + + +### settings + +Return settings. + +## Methods + +### assignment\_matrix + + + +`assignment_matrix(qubits=None)` + +Return the readout assignment matrix for specified qubits. + +The assignment matrix is the stochastic matrix $A$ which assigns a noisy readout probability distribution to an ideal input readout distribution: $P(i|j) = \langle i | A | j \rangle$. + +**Parameters** + +**qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, qubits being measured. + +**Returns** + +the assignment matrix A. + +**Return type** + +np.ndarray + +### expectation\_value + + + +`expectation_value(data, diagonal=None, qubits=None, clbits=None, shots=None)` + +Compute the mitigated expectation value of a diagonal observable. + +This computes the mitigated estimator of $\langle O \rangle = \mbox{Tr}[\rho. O]$ of a diagonal observable $O = \sum_{x\in\{0, 1\}^n} O(x)|x\rangle\!\langle x|$. + +**Parameters** + +* **data** ([*Counts*](qiskit.result.Counts "qiskit.result.counts.Counts")) – Counts object +* **diagonal** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *| None*) – Optional, the vector of diagonal values for summing the expectation value. If `None` the default value is $[1, -1]^\otimes n$. +* **qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, the measured physical qubits the count bitstrings correspond to. If None qubits are assumed to be $[0, ..., n-1]$. +* **clbits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, if not None marginalize counts to the specified bits. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – the number of shots. + +**Returns** + +the expectation value and an upper bound of the standard deviation. + +**Return type** + +([float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) + +**Additional Information:** + +The diagonal observable $O$ is input using the `diagonal` kwarg as a list or Numpy array $[O(0), ..., O(2^n -1)]$. If no diagonal is specified the diagonal of the Pauli operator :math\`O = mbox\{diag}(Z^\{otimes n}) = \[1, -1]^\{otimes n}\` is used. The `clbits` kwarg is used to marginalize the input counts dictionary over the specified bit-values, and the `qubits` kwarg is used to specify which physical qubits these bit-values correspond to as `circuit.measure(qubits, clbits)`. + +### mitigation\_matrix + + + +`mitigation_matrix(qubits=None)` + +Return the readout mitigation matrix for the specified qubits. + +The mitigation matrix $A^{-1}$ is defined as the inverse of the [`assignment_matrix()`](#qiskit.result.CorrelatedReadoutMitigator.assignment_matrix "qiskit.result.CorrelatedReadoutMitigator.assignment_matrix") $A$. + +**Parameters** + +**qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, qubits being measured. + +**Returns** + +the measurement error mitigation matrix $A^{-1}$. + +**Return type** + +np.ndarray + +### quasi\_probabilities + + + +`quasi_probabilities(data, qubits=None, clbits=None, shots=None)` + +Compute mitigated quasi probabilities value. + +**Parameters** + +* **data** ([*Counts*](qiskit.result.Counts "qiskit.result.counts.Counts")) – counts object +* **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – qubits the count bitstrings correspond to. +* **clbits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, marginalize counts to just these bits. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional, the total number of shots, if None shots will be calculated as the sum of all counts. + +**Returns** + +**A dictionary containing pairs of \[output, mean] where “output”** + +is the key in the dictionaries, which is the length-N bitstring of a measured standard basis state, and “mean” is the mean of non-zero quasi-probability estimates. + +**Return type** + +[QuasiDistribution](qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution") + +### stddev\_upper\_bound + + + +`stddev_upper_bound(shots)` + +Return an upper bound on standard deviation of expval estimator. + +**Parameters** + +**shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of shots used for expectation value measurement. + +**Returns** + +the standard deviation upper bound. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.result.Counts.md b/docs/api/qiskit/0.46/qiskit.result.Counts.md new file mode 100644 index 00000000000..2463622a5b4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.Counts.md @@ -0,0 +1,204 @@ +--- +title: Counts +description: API reference for qiskit.result.Counts +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.Counts +--- + +# Counts + + + +`qiskit.result.Counts(data, time_taken=None, creg_sizes=None, memory_slots=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/counts.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +A class to store a counts result from a circuit execution. + +Build a counts object + +**Parameters** + +* **data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + The dictionary input for the counts. Where the keys represent a measured classical value and the value is an integer the number of shots with that result. The keys can be one of several formats: + + > * A hexadecimal string of the form `'0x4a'` + > * A bit string prefixed with `0b` for example `'0b1011'` + > * A bit string formatted across register and memory slots. For example, `'00 10'`. + > * A dit string, for example `'02'`. Note for objects created with dit strings the `creg_sizes` and `memory_slots` kwargs don’t work and [`hex_outcomes()`](#qiskit.result.Counts.hex_outcomes "qiskit.result.Counts.hex_outcomes") and [`int_outcomes()`](#qiskit.result.Counts.int_outcomes "qiskit.result.Counts.int_outcomes") also do not work. + +* **time\_taken** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The duration of the experiment that generated the counts in seconds. + +* **creg\_sizes** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a nested list where the inner element is a list of tuples containing both the classical register name and classical register size. For example, `[('c_reg', 2), ('my_creg', 4)]`. + +* **memory\_slots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of total `memory_slots` in the experiment. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the input key type is not an `int` or `str`. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a dit string key is input with `creg_sizes` and/or `memory_slots`. + +## Attributes + + + +### bitstring\_regex + +`= re.compile('^[01\\s]+$')` + +## Methods + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### hex\_outcomes + + + +`hex_outcomes()` + +Return a counts dictionary with hexadecimal string keys + +**Returns** + +**A dictionary with the keys as hexadecimal strings instead of** + +bitstrings + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the Counts object contains counts for dit strings + +### int\_outcomes + + + +`int_outcomes()` + +Build a counts dictionary with integer keys instead of count strings + +**Returns** + +A dictionary with the keys as integers instead of bitstrings + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the Counts object contains counts for dit strings + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### most\_frequent + + + +`most_frequent()` + +Return the most frequent count + +**Returns** + +The bit string for the most frequent result + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – when there is >1 count with the same max counts, or an empty object. + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### shots + + + +`shots()` + +Return the number of shots + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.result.LocalReadoutMitigator.md b/docs/api/qiskit/0.46/qiskit.result.LocalReadoutMitigator.md new file mode 100644 index 00000000000..8889015fe0e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.LocalReadoutMitigator.md @@ -0,0 +1,172 @@ +--- +title: LocalReadoutMitigator +description: API reference for qiskit.result.LocalReadoutMitigator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.LocalReadoutMitigator +--- + +# LocalReadoutMitigator + + + +`qiskit.result.LocalReadoutMitigator(assignment_matrices=None, qubits=None, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/mitigation/local_readout_mitigator.py "view source code") + +Bases: [`BaseReadoutMitigator`](qiskit.result.BaseReadoutMitigator "qiskit.result.mitigation.base_readout_mitigator.BaseReadoutMitigator") + +1-qubit tensor product readout error mitigator. + +Mitigates [`expectation_value()`](#qiskit.result.LocalReadoutMitigator.expectation_value "qiskit.result.LocalReadoutMitigator.expectation_value") and [`quasi_probabilities()`](#qiskit.result.LocalReadoutMitigator.quasi_probabilities "qiskit.result.LocalReadoutMitigator.quasi_probabilities"). The mitigator should either be calibrated using qiskit experiments, or calculated directly from the backend properties. This mitigation method should be used in case the readout errors of the qubits are assumed to be uncorrelated. For *N* qubits there are *N* mitigation matrices, each of size $2 x 2$ and the mitigation complexity is $O(2^N)$, so it is more efficient than the [`CorrelatedReadoutMitigator`](qiskit.result.CorrelatedReadoutMitigator "qiskit.result.CorrelatedReadoutMitigator") class. + +Initialize a LocalReadoutMitigator + +**Parameters** + +* **assignment\_matrices** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")*] | None*) – Optional, list of single-qubit readout error assignment matrices. +* **qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, the measured physical qubits for mitigation. +* **backend** – Optional, backend name. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – matrices sizes do not agree with number of qubits + +## Attributes + + + +### qubits + +The device qubits for this mitigator + + + +### settings + +Return settings. + +## Methods + +### assignment\_matrix + + + +`assignment_matrix(qubits=None)` + +Return the measurement assignment matrix for specified qubits. + +The assignment matrix is the stochastic matrix $A$ which assigns a noisy measurement probability distribution to an ideal input measurement distribution: $P(i|j) = \langle i | A | j \rangle$. + +**Parameters** + +**qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, qubits being measured for operator expval. + +**Returns** + +the assignment matrix A. + +**Return type** + +np.ndarray + +### expectation\_value + + + +`expectation_value(data, diagonal=None, qubits=None, clbits=None, shots=None)` + +Compute the mitigated expectation value of a diagonal observable. + +This computes the mitigated estimator of $\langle O \rangle = \mbox{Tr}[\rho. O]$ of a diagonal observable $O = \sum_{x\in\{0, 1\}^n} O(x)|x\rangle\!\langle x|$. + +**Parameters** + +* **data** ([*Counts*](qiskit.result.Counts "qiskit.result.counts.Counts")) – Counts object +* **diagonal** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") *| None*) – Optional, the vector of diagonal values for summing the expectation value. If `None` the default value is $[1, -1]^\otimes n$. +* **qubits** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, the measured physical qubits the count bitstrings correspond to. If None qubits are assumed to be $[0, ..., n-1]$. +* **clbits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, if not None marginalize counts to the specified bits. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – the number of shots. + +**Returns** + +the expectation value and an upper bound of the standard deviation. + +**Return type** + +([float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) + +**Additional Information:** + +The diagonal observable $O$ is input using the `diagonal` kwarg as a list or Numpy array $[O(0), ..., O(2^n -1)]$. If no diagonal is specified the diagonal of the Pauli operator :math\`O = mbox\{diag}(Z^\{otimes n}) = \[1, -1]^\{otimes n}\` is used. The `clbits` kwarg is used to marginalize the input counts dictionary over the specified bit-values, and the `qubits` kwarg is used to specify which physical qubits these bit-values correspond to as `circuit.measure(qubits, clbits)`. + +### mitigation\_matrix + + + +`mitigation_matrix(qubits=None)` + +Return the measurement mitigation matrix for the specified qubits. + +The mitigation matrix $A^{-1}$ is defined as the inverse of the [`assignment_matrix()`](#qiskit.result.LocalReadoutMitigator.assignment_matrix "qiskit.result.LocalReadoutMitigator.assignment_matrix") $A$. + +**Parameters** + +**qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] |* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional, qubits being measured for operator expval. if a single int is given, it is assumed to be the index of the qubit in self.\_qubits + +**Returns** + +the measurement error mitigation matrix $A^{-1}$. + +**Return type** + +np.ndarray + +### quasi\_probabilities + + + +`quasi_probabilities(data, qubits=None, clbits=None, shots=None)` + +Compute mitigated quasi probabilities value. + +**Parameters** + +* **data** ([*Counts*](qiskit.result.Counts "qiskit.result.counts.Counts")) – counts object +* **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – qubits the count bitstrings correspond to. +* **clbits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Optional, marginalize counts to just these bits. +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional, the total number of shots, if None shots will be calculated as the sum of all counts. + +**Returns** + +**A dictionary containing pairs of \[output, mean] where “output”** + +is the key in the dictionaries, which is the length-N bitstring of a measured standard basis state, and “mean” is the mean of non-zero quasi-probability estimates. + +**Return type** + +[QuasiDistribution](qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if qubit and clbit kwargs are not valid. + +### stddev\_upper\_bound + + + +`stddev_upper_bound(shots, qubits=None)` + +Return an upper bound on standard deviation of expval estimator. + +**Parameters** + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of shots used for expectation value measurement. +* **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – qubits being measured for operator expval. + +**Returns** + +the standard deviation upper bound. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.result.ProbDistribution.md b/docs/api/qiskit/0.46/qiskit.result.ProbDistribution.md new file mode 100644 index 00000000000..6147752712f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.ProbDistribution.md @@ -0,0 +1,161 @@ +--- +title: ProbDistribution +description: API reference for qiskit.result.ProbDistribution +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.ProbDistribution +--- + +# ProbDistribution + + + +`qiskit.result.ProbDistribution(data, shots=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/distributions/probability.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +A generic dict-like class for probability distributions. + +Builds a probability distribution object. + +**Parameters** + +* **data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + Input probability data. Where the keys represent a measured classical value and the value is a float for the probability of that result. The keys can be one of several formats: + + > * A hexadecimal string of the form `"0x4a"` + > * A bit string e.g. `'0b1011'` or `"01011"` + > * An integer + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of shots the distribution was derived from. + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the input keys are not a string or int +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the string format of the keys is incorrect + +## Methods + +### binary\_probabilities + + + +`binary_probabilities(num_bits=None)` + +Build a probabilities dictionary with binary string keys + +**Parameters** + +**num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of bits in the binary bitstrings (leading zeros will be padded). If None, a default value will be used. If keys are given as integers or strings with binary or hex prefix, the default value will be derived from the largest key present. If keys are given as bitstrings without prefix, the default value will be derived from the largest key length. + +**Returns** + +**A dictionary where the keys are binary strings in the format** + +`"0110"` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### hex\_probabilities + + + +`hex_probabilities()` + +Build a probabilities dictionary with hexadecimal string keys + +**Returns** + +**A dictionary where the keys are hexadecimal strings in the** + +format `"0x1a"` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.result.QuasiDistribution.md b/docs/api/qiskit/0.46/qiskit.result.QuasiDistribution.md new file mode 100644 index 00000000000..8dfd0625c64 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.QuasiDistribution.md @@ -0,0 +1,199 @@ +--- +title: QuasiDistribution +description: API reference for qiskit.result.QuasiDistribution +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.QuasiDistribution +--- + +# QuasiDistribution + + + +`qiskit.result.QuasiDistribution(data, shots=None, stddev_upper_bound=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/distributions/quasi.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +A dict-like class for representing quasi-probabilities. + +Builds a quasiprobability distribution object. + + + The quasiprobability values might include floating-point errors. `QuasiDistribution.__repr__` rounds using `numpy.round()` and the parameter `ndigits` can be manipulated with the class attribute `__ndigits__`. The default is `15`. + + +**Parameters** + +* **data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + Input quasiprobability data. Where the keys represent a measured classical value and the value is a float for the quasiprobability of that result. The keys can be one of several formats: + + > * A hexadecimal string of the form `"0x4a"` + > * A bit string e.g. `'0b1011'` or `"01011"` + > * An integer + +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of shots the distribution was derived from. + +* **stddev\_upper\_bound** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – An upper bound for the standard deviation + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If the input keys are not a string or int +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the string format of the keys is incorrect + +## Attributes + + + +### stddev\_upper\_bound + +Return an upper bound on standard deviation of expval estimator. + +## Methods + +### binary\_probabilities + + + +`binary_probabilities(num_bits=None)` + +Build a quasi-probabilities dictionary with binary string keys + +**Parameters** + +**num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of bits in the binary bitstrings (leading zeros will be padded). If None, a default value will be used. If keys are given as integers or strings with binary or hex prefix, the default value will be derived from the largest key present. If keys are given as bitstrings without prefix, the default value will be derived from the largest key length. + +**Returns** + +**A dictionary where the keys are binary strings in the format** + +`"0110"` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### hex\_probabilities + + + +`hex_probabilities()` + +Build a quasi-probabilities dictionary with hexadecimal string keys + +**Returns** + +**A dictionary where the keys are hexadecimal strings in the** + +format `"0x1a"` + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### nearest\_probability\_distribution + + + +`nearest_probability_distribution(return_distance=False)` + +Takes a quasiprobability distribution and maps it to the closest probability distribution as defined by the L2-norm. + +**Parameters** + +**return\_distance** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Return the L2 distance between distributions. + +**Returns** + +Nearest probability distribution. float: Euclidean (L2) distance of distributions. + +**Return type** + +[ProbDistribution](qiskit.result.ProbDistribution "qiskit.result.ProbDistribution") + +**Notes** + +Method from Smolin et al., Phys. Rev. Lett. 108, 070502 (2012). + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.result.Result.md b/docs/api/qiskit/0.46/qiskit.result.Result.md new file mode 100644 index 00000000000..4f6ea159e19 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.Result.md @@ -0,0 +1,258 @@ +--- +title: Result +description: API reference for qiskit.result.Result +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.result.Result +--- + +# Result + + + +`qiskit.result.Result(backend_name, backend_version, qobj_id, job_id, success, results, date=None, status=None, header=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/result.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Model for Results. + + + +### backend\_name + +backend name. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + + + +### backend\_version + +backend version, in the form X.Y.Z. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + + + +### qobj\_id + +user-generated Qobj id. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + + + +### job\_id + +unique execution id from the backend. + +**Type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + + + +### success + +True if complete input qobj executed correctly. (Implies each experiment success) + +**Type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + + + +### results + +corresponding results for array of experiments of the input qobj + +**Type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[ExperimentResult] + +## Methods + +### data + + + +`data(experiment=None)` + +Get the raw data for an experiment. + +Note this data will be a single classical and quantum register and in a format required by the results schema. We recommend that most users use the get\_xxx method, and the data will be post-processed for the data type. + +**Parameters** + +**experiment** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or None*) – the index of the experiment. Several types are accepted for convenience:: \* str: the name of the experiment. \* QuantumCircuit: the name of the circuit instance will be used. \* Schedule: the name of the schedule instance will be used. \* int: the position of the experiment. \* None: if there is only one experiment, returns it. + +**Returns** + +A dictionary of results data for an experiment. The data depends on the backend it ran on and the settings of meas\_level, meas\_return and memory. + +OpenQASM backends return a dictionary of dictionary with the key ‘counts’ and with the counts, with the second dictionary keys containing a string in hex format (`0x123`) and values equal to the number of times this outcome was measured. + +Statevector backends return a dictionary with key ‘statevector’ and values being a list\[list\[complex components]] list of 2^num\_qubits complex amplitudes. Where each complex number is represented as a 2 entry list for each component. For example, a list of \[0.5+1j, 0-1j] would be represented as \[\[0.5, 1], \[0, -1]]. + +Unitary backends return a dictionary with key ‘unitary’ and values being a list\[list\[list\[complex components]]] list of 2^num\_qubits x 2^num\_qubits complex amplitudes in a two entry list for each component. For example if the amplitude is \[\[0.5+0j, 0-1j], …] the value returned will be \[\[\[0.5, 0], \[0, -1]], …]. + +The simulator backends also have an optional key ‘snapshots’ which returns a dict of snapshots specified by the simulator backend. The value is of the form dict\[slot: dict\[str: array]] where the keys are the requested snapshot slots, and the values are a dictionary of the snapshots. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if data for the experiment could not be retrieved. + +### from\_dict + + + +`classmethod from_dict(data)` + +Create a new ExperimentResultData object from a dictionary. + +**Parameters** + +**data** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary representing the Result to create. It will be in the same format as output by [`to_dict()`](#qiskit.result.Result.to_dict "qiskit.result.Result.to_dict"). + +**Returns** + +The `Result` object from the input dictionary. + +**Return type** + +[Result](#qiskit.result.Result "qiskit.result.Result") + +### get\_counts + + + +`get_counts(experiment=None)` + +Get the histogram data of an experiment. + +**Parameters** + +**experiment** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or None*) – the index of the experiment, as specified by `data([experiment])`. + +**Returns** + +a dictionary or a list of dictionaries. A dictionary has the counts for each qubit with the keys containing a string in binary format and separated according to the registers in circuit (e.g. `0100 1110`). The string is little-endian (cr\[0] on the right hand side). + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] or [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if there are no counts for the experiment. + +### get\_memory + + + +`get_memory(experiment=None)` + +Get the sequence of memory states (readouts) for each shot The data from the experiment is a list of format \[‘00000’, ‘01000’, ‘10100’, ‘10100’, ‘11101’, ‘11100’, ‘00101’, …, ‘01010’] + +**Parameters** + +**experiment** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or None*) – the index of the experiment, as specified by `data()`. + +**Returns** + +Either the list of each outcome, formatted according to registers in circuit or a complex numpy np.ndarray with shape: + +> | meas\_level | meas\_return | shape | +> | ----------- | ------------ | ----------------------------------------------------- | +> | 0 | single | np.ndarray\[shots, memory\_slots, memory\_slot\_size] | +> | 0 | avg | np.ndarray\[memory\_slots, memory\_slot\_size] | +> | 1 | single | np.ndarray\[shots, memory\_slots] | +> | 1 | avg | np.ndarray\[memory\_slots] | +> | 2 | memory=True | list | + +**Return type** + +List\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] or np.ndarray + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if there is no memory data for the circuit. + +### get\_statevector + + + +`get_statevector(experiment=None, decimals=None)` + +Get the final statevector of an experiment. + +**Parameters** + +* **experiment** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or None*) – the index of the experiment, as specified by `data()`. +* **decimals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimals in the statevector. If None, does not round. + +**Returns** + +list of 2^num\_qubits complex amplitudes. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if there is no statevector for the experiment. + +### get\_unitary + + + +`get_unitary(experiment=None, decimals=None)` + +Get the final unitary of an experiment. + +**Parameters** + +* **experiment** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or None*) – the index of the experiment, as specified by `data()`. +* **decimals** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of decimals in the unitary. If None, does not round. + +**Returns** + +**list of 2^num\_qubits x 2^num\_qubits complex** + +amplitudes. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")]] + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if there is no unitary for the experiment. + +### to\_dict + + + +`to_dict()` + +Return a dictionary format representation of the Result + +**Returns** + +The dictionary form of the Result + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.result.ResultError.md b/docs/api/qiskit/0.46/qiskit.result.ResultError.md new file mode 100644 index 00000000000..0b85c4263fa --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.result.ResultError.md @@ -0,0 +1,34 @@ +--- +title: ResultError +description: API reference for qiskit.result.ResultError +in_page_toc_min_heading_level: 1 +python_api_type: exception +python_api_name: qiskit.result.ResultError +--- + + + +# qiskit.result.ResultError + + + +`qiskit.result.ResultError(error)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/exceptions.py "view source code") + +Exceptions raised due to errors in result output. + +It may be better for the Qiskit API to raise this exception. + +**Parameters** + +**error** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + +This is the error record as it comes back from the API. The format is like: + +```python +error = {'status': 403, + 'message': 'Your credits are not enough.', + 'code': 'MAX_CREDITS_EXCEEDED'} +``` + +Set the error message. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.EvolutionSynthesis.md b/docs/api/qiskit/0.46/qiskit.synthesis.EvolutionSynthesis.md new file mode 100644 index 00000000000..38f188708e5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.EvolutionSynthesis.md @@ -0,0 +1,56 @@ +--- +title: EvolutionSynthesis +description: API reference for qiskit.synthesis.EvolutionSynthesis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.EvolutionSynthesis +--- + +# EvolutionSynthesis + + + +`qiskit.synthesis.EvolutionSynthesis`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/evolution/evolution_synthesis.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Interface for evolution synthesis algorithms. + +## Attributes + + + +### settings + +Return the settings in a dictionary, which can be used to reconstruct the object. + +**Returns** + +A dictionary containing the settings of this product formula. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – The interface does not implement this method. + +## Methods + +### synthesize + + + +`abstract synthesize(evolution)` + +Synthesize an `qiskit.circuit.library.PauliEvolutionGate`. + +**Parameters** + +**evolution** ([*PauliEvolutionGate*](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")) – The evolution gate to synthesize. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.LieTrotter.md b/docs/api/qiskit/0.46/qiskit.synthesis.LieTrotter.md new file mode 100644 index 00000000000..c2a67d99289 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.LieTrotter.md @@ -0,0 +1,79 @@ +--- +title: LieTrotter +description: API reference for qiskit.synthesis.LieTrotter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.LieTrotter +--- + +# LieTrotter + + + +`qiskit.synthesis.LieTrotter(reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/evolution/lie_trotter.py "view source code") + +Bases: [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.evolution.product_formula.ProductFormula") + +The Lie-Trotter product formula. + +The Lie-Trotter formula approximates the exponential of two non-commuting operators with products of their exponentials up to a second order error: + +$$ +e^{A + B} \approx e^{A}e^{B}. +$$ + +In this implementation, the operators are provided as sum terms of a Pauli operator. For example, we approximate + +$$ +e^{-it(XX + ZZ)} = e^{-it XX}e^{-it ZZ} + \mathcal{O}(t^2). +$$ + +**References** + +\[1]: D. Berry, G. Ahokas, R. Cleve and B. Sanders, “Efficient quantum algorithms for simulating sparse Hamiltonians” (2006). [arXiv:quant-ph/0508139](https://arxiv.org/abs/quant-ph/0508139) \[2]: N. Hatano and M. Suzuki, “Finding Exponential Product Formulas of Higher Orders” (2005). [arXiv:math-ph/0506007](https://arxiv.org/pdf/math-ph/0506007.pdf) + +**Parameters** + +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of time steps. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to insert barriers between the atomic evolutions. +* **cx\_structure** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – How to arrange the CX gates for the Pauli evolutions, can be “chain”, where next neighbor connections are used, or “fountain”, where all qubits are connected to one. +* **atomic\_evolution** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] | None*) – A function to construct the circuit for the evolution of single Pauli string. Per default, a single Pauli evolution is decomposed in a CX chain and a single qubit Z rotation. + +## Attributes + + + +### settings + +Return the settings in a dictionary, which can be used to reconstruct the object. + +**Returns** + +A dictionary containing the settings of this product formula. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If a custom atomic evolution is set, which cannot be serialized. + +## Methods + +### synthesize + + + +`synthesize(evolution)` + +Synthesize an `qiskit.circuit.library.PauliEvolutionGate`. + +**Parameters** + +**evolution** ([*PauliEvolutionGate*](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")) – The evolution gate to synthesize. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.MatrixExponential.md b/docs/api/qiskit/0.46/qiskit.synthesis.MatrixExponential.md new file mode 100644 index 00000000000..176cc0dc69c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.MatrixExponential.md @@ -0,0 +1,58 @@ +--- +title: MatrixExponential +description: API reference for qiskit.synthesis.MatrixExponential +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.MatrixExponential +--- + +# MatrixExponential + + + +`qiskit.synthesis.MatrixExponential`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/evolution/matrix_synthesis.py "view source code") + +Bases: [`EvolutionSynthesis`](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.evolution.evolution_synthesis.EvolutionSynthesis") + +Exact operator evolution via matrix exponentiation and unitary synthesis. + +This class synthesis the exponential of operators by calculating their exponentially-sized matrix representation and using exact matrix exponentiation followed by unitary synthesis to obtain a circuit. This process is not scalable and serves as comparison or benchmark for small systems. + +## Attributes + + + +### settings + +Return the settings in a dictionary, which can be used to reconstruct the object. + +**Returns** + +A dictionary containing the settings of this product formula. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – The interface does not implement this method. + +## Methods + +### synthesize + + + +`synthesize(evolution)` + +Synthesize an `qiskit.circuit.library.PauliEvolutionGate`. + +**Parameters** + +**evolution** ([*PauliEvolutionGate*](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")) – The evolution gate to synthesize. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.OneQubitEulerDecomposer.md b/docs/api/qiskit/0.46/qiskit.synthesis.OneQubitEulerDecomposer.md new file mode 100644 index 00000000000..60fcee0838a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.OneQubitEulerDecomposer.md @@ -0,0 +1,106 @@ +--- +title: OneQubitEulerDecomposer +description: API reference for qiskit.synthesis.OneQubitEulerDecomposer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.OneQubitEulerDecomposer +--- + +# OneQubitEulerDecomposer + + + +`qiskit.synthesis.OneQubitEulerDecomposer(basis='U3', use_dag=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/one_qubit/one_qubit_decompose.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A class for decomposing 1-qubit unitaries into Euler angle rotations. + +The resulting decomposition is parameterized by 3 Euler rotation angle parameters $(\theta, \phi, \lambda)$, and a phase parameter $\gamma$. The value of the parameters for an input unitary depends on the decomposition basis. Allowed bases and the resulting circuits are shown in the following table. Note that for the non-Euler bases (U3, U1X, RR), the ZYZ Euler parameters are used. + +| Basis | Euler Angle Basis | Decomposition Circuit | +| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| ‘ZYZ’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} R_Z(\phi).R_Y(\theta).R_Z(\lambda)$ | +| ‘ZXZ’ | $Z(\phi) X(\theta) Z(\lambda)$ | $e^{i\gamma} R_Z(\phi).R_X(\theta).R_Z(\lambda)$ | +| ‘XYX’ | $X(\phi) Y(\theta) X(\lambda)$ | $e^{i\gamma} R_X(\phi).R_Y(\theta).R_X(\lambda)$ | +| ‘XZX’ | $X(\phi) Z(\theta) X(\lambda)$ | $e^{i\gamma} R_X(\phi).R_Z(\theta).R_X(\lambda)$ | +| ‘U3’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} U_3(\theta,\phi,\lambda)$ | +| ‘U321’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} U_3(\theta,\phi,\lambda)$ | +| ‘U’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} U_3(\theta,\phi,\lambda)$ | +| ‘PSX’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} U_1(\phi+\pi).R_X\left(\frac{\pi}{2}\right).$ $U_1(\theta+\pi).R_X\left(\frac{\pi}{2}\right).U_1(\lambda)$ | +| ‘ZSX’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} R_Z(\phi+\pi).\sqrt{X}.$ $R_Z(\theta+\pi).\sqrt{X}.R_Z(\lambda)$ | +| ‘ZSXX’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} R_Z(\phi+\pi).\sqrt{X}.R_Z(\theta+\pi).\sqrt{X}.R_Z(\lambda)$ or $e^{i\gamma} R_Z(\phi+\pi).X.R_Z(\lambda)$ | +| ‘U1X’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} U_1(\phi+\pi).R_X\left(\frac{\pi}{2}\right).$ $U_1(\theta+\pi).R_X\left(\frac{\pi}{2}\right).U_1(\lambda)$ | +| ‘RR’ | $Z(\phi) Y(\theta) Z(\lambda)$ | $e^{i\gamma} R\left(-\pi,\frac{\phi-\lambda+\pi}{2}\right).$ $R\left(\theta+\pi,\frac{\pi}{2}-\lambda\right)$ | + +Initialize decomposer + +Supported bases are: ‘U’, ‘PSX’, ‘ZSXX’, ‘ZSX’, ‘U321’, ‘U3’, ‘U1X’, ‘RR’, ‘ZYZ’, ‘ZXZ’, ‘XYX’, ‘XZX’. + +**Parameters** + +* **basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the decomposition basis \[Default: ‘U3’] +* **use\_dag** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If true the output from calls to the decomposer will be a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object instead of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If input basis is not recognized. + +## Attributes + + + +### basis + +The decomposition basis. + +## Methods + +### angles + + + +`angles(unitary)` + +Return the Euler angles for input array. + +**Parameters** + +**unitary** (*np.ndarray*) – 2x2 unitary matrix. + +**Returns** + +(theta, phi, lambda). + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### angles\_and\_phase + + + +`angles_and_phase(unitary)` + +Return the Euler angles and phase for input array. + +**Parameters** + +**unitary** (*np.ndarray*) – 2x2 unitary matrix. + +**Returns** + +(theta, phi, lambda, phase). + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") + +### build\_circuit + + + +`build_circuit(gates, global_phase)` + +Return the circuit or dag object from a list of gates. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.ProductFormula.md b/docs/api/qiskit/0.46/qiskit.synthesis.ProductFormula.md new file mode 100644 index 00000000000..6f394b17856 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.ProductFormula.md @@ -0,0 +1,66 @@ +--- +title: ProductFormula +description: API reference for qiskit.synthesis.ProductFormula +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.ProductFormula +--- + +# ProductFormula + + + +`qiskit.synthesis.ProductFormula(order, reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/evolution/product_formula.py "view source code") + +Bases: [`EvolutionSynthesis`](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.evolution.evolution_synthesis.EvolutionSynthesis") + +Product formula base class for the decomposition of non-commuting operator exponentials. + +[`LieTrotter`](qiskit.synthesis.LieTrotter "qiskit.synthesis.LieTrotter") and [`SuzukiTrotter`](qiskit.synthesis.SuzukiTrotter "qiskit.synthesis.SuzukiTrotter") inherit from this class. + +**Parameters** + +* **order** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The order of the product formula. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of time steps. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to insert barriers between the atomic evolutions. +* **cx\_structure** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – How to arrange the CX gates for the Pauli evolutions, can be “chain”, where next neighbor connections are used, or “fountain”, where all qubits are connected to one. +* **atomic\_evolution** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] | None*) – A function to construct the circuit for the evolution of single Pauli string. Per default, a single Pauli evolution is decomposed in a CX chain and a single qubit Z rotation. + +## Attributes + + + +### settings + +Return the settings in a dictionary, which can be used to reconstruct the object. + +**Returns** + +A dictionary containing the settings of this product formula. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If a custom atomic evolution is set, which cannot be serialized. + +## Methods + +### synthesize + + + +`abstract synthesize(evolution)` + +Synthesize an `qiskit.circuit.library.PauliEvolutionGate`. + +**Parameters** + +**evolution** ([*PauliEvolutionGate*](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")) – The evolution gate to synthesize. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.QDrift.md b/docs/api/qiskit/0.46/qiskit.synthesis.QDrift.md new file mode 100644 index 00000000000..4d721a710ec --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.QDrift.md @@ -0,0 +1,68 @@ +--- +title: QDrift +description: API reference for qiskit.synthesis.QDrift +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.QDrift +--- + +# QDrift + + + +`qiskit.synthesis.QDrift(reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/evolution/qdrift.py "view source code") + +Bases: [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.evolution.product_formula.ProductFormula") + +The QDrift Trotterization method, which selects each each term in the Trotterization randomly, with a probability proportional to its weight. Based on the work of Earl Campbell in Ref. \[1]. + +**References** + +\[1]: E. Campbell, “A random compiler for fast Hamiltonian simulation” (2018). [arXiv:quant-ph/1811.08017](https://arxiv.org/abs/1811.08017) + +**Parameters** + +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of times to repeat the Trotterization circuit. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to insert barriers between the atomic evolutions. +* **cx\_structure** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – How to arrange the CX gates for the Pauli evolutions, can be “chain”, where next neighbor connections are used, or “fountain”, where all qubits are connected to one. +* **atomic\_evolution** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] | None*) – A function to construct the circuit for the evolution of single Pauli string. Per default, a single Pauli evolution is decomposed in a CX chain and a single qubit Z rotation. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – An optional seed for reproducibility of the random sampling process. + +## Attributes + + + +### settings + +Return the settings in a dictionary, which can be used to reconstruct the object. + +**Returns** + +A dictionary containing the settings of this product formula. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If a custom atomic evolution is set, which cannot be serialized. + +## Methods + +### synthesize + + + +`synthesize(evolution)` + +Synthesize an `qiskit.circuit.library.PauliEvolutionGate`. + +**Parameters** + +**evolution** ([*PauliEvolutionGate*](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")) – The evolution gate to synthesize. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.SolovayKitaevDecomposition.md b/docs/api/qiskit/0.46/qiskit.synthesis.SolovayKitaevDecomposition.md new file mode 100644 index 00000000000..1fd4a0c057e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.SolovayKitaevDecomposition.md @@ -0,0 +1,93 @@ +--- +title: SolovayKitaevDecomposition +description: API reference for qiskit.synthesis.SolovayKitaevDecomposition +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.SolovayKitaevDecomposition +--- + +# SolovayKitaevDecomposition + + + +`qiskit.synthesis.SolovayKitaevDecomposition(basic_approximations=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/discrete_basis/solovay_kitaev.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +The Solovay Kitaev discrete decomposition algorithm. + +This class is called recursively by the transpiler pass, which is why it is separeted. See [`qiskit.transpiler.passes.SolovayKitaev`](qiskit.transpiler.passes.SolovayKitaev "qiskit.transpiler.passes.SolovayKitaev") for more information. + +**Parameters** + +**basic\_approximations** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, np.ndarray] |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[GateSequence] | None*) – A specification of the basic SU(2) approximations in terms of discrete gates. At each iteration this algorithm, the remaining error is approximated with the closest sequence of gates in this set. If a `str`, this specifies a `.npy` filename from which to load the approximation. If a `dict`, then this contains `{gates: effective_SO3_matrix}` pairs, e.g. `{"h t": np.array([[0, 0.7071, -0.7071], [0, -0.7071, -0.7071], [-1, 0, 0]]}`. If a list, this contains the same information as the dict, but already converted to `GateSequence` objects, which contain the SO(3) matrix and gates. + +## Methods + +### find\_basic\_approximation + + + +`find_basic_approximation(sequence)` + +Finds gate in `self._basic_approximations` that best represents `sequence`. + +**Parameters** + +**sequence** (*GateSequence*) – The gate to find the approximation to. + +**Returns** + +Gate in basic approximations that is closest to `sequence`. + +**Return type** + +[*Gate*](qiskit.circuit.Gate "qiskit.circuit.gate.Gate") + +### load\_basic\_approximations + + + +`load_basic_approximations(data)` + +Load basic approximations. + +**Parameters** + +**data** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – If a string, specifies the path to the file from where to load the data. If a dictionary, directly specifies the decompositions as `{gates: matrix}`. There `gates` are the names of the gates producing the SO(3) matrix `matrix`, e.g. `{"h t": np.array([[0, 0.7071, -0.7071], [0, -0.7071, -0.7071], [-1, 0, 0]]}`. + +**Returns** + +A list of basic approximations as type `GateSequence`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the number of gate combinations and associated matrices does not match. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[GateSequence] + +### run + + + +`run(gate_matrix, recursion_degree, return_dag=False, check_input=True)` + +Run the algorithm. + +**Parameters** + +* **gate\_matrix** (*np.ndarray*) – The 2x2 matrix representing the gate. This matrix has to be SU(2) up to global phase. +* **recursion\_degree** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The recursion degree, called $n$ in the paper. +* **return\_dag** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` return a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit"), else a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). +* **check\_input** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` check that the input matrix is valid for the decomposition. + +**Returns** + +A one-qubit circuit approximating the `gate_matrix` in the specified discrete basis. + +**Return type** + +QuantumCircuit’ | ‘DAGCircuit + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.SuzukiTrotter.md b/docs/api/qiskit/0.46/qiskit.synthesis.SuzukiTrotter.md new file mode 100644 index 00000000000..46fc16e05ae --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.SuzukiTrotter.md @@ -0,0 +1,86 @@ +--- +title: SuzukiTrotter +description: API reference for qiskit.synthesis.SuzukiTrotter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.SuzukiTrotter +--- + +# SuzukiTrotter + + + +`qiskit.synthesis.SuzukiTrotter(order=2, reps=1, insert_barriers=False, cx_structure='chain', atomic_evolution=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/evolution/suzuki_trotter.py "view source code") + +Bases: [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.evolution.product_formula.ProductFormula") + +The (higher order) Suzuki-Trotter product formula. + +The Suzuki-Trotter formulas improve the error of the Lie-Trotter approximation. For example, the second order decomposition is + +$$ +e^{A + B} \approx e^{B/2} e^{A} e^{B/2}. +$$ + +Higher order decompositions are based on recursions, see Ref. \[1] for more details. + +In this implementation, the operators are provided as sum terms of a Pauli operator. For example, in the second order Suzuki-Trotter decomposition we approximate + +$$ +e^{-it(XX + ZZ)} = e^{-it/2 ZZ}e^{-it XX}e^{-it/2 ZZ} + \mathcal{O}(t^3). +$$ + +**References** + +\[1]: D. Berry, G. Ahokas, R. Cleve and B. Sanders, “Efficient quantum algorithms for simulating sparse Hamiltonians” (2006). [arXiv:quant-ph/0508139](https://arxiv.org/abs/quant-ph/0508139) \[2]: N. Hatano and M. Suzuki, “Finding Exponential Product Formulas of Higher Orders” (2005). [arXiv:math-ph/0506007](https://arxiv.org/pdf/math-ph/0506007.pdf) + +**Parameters** + +* **order** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The order of the product formula. +* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of time steps. +* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to insert barriers between the atomic evolutions. +* **cx\_structure** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – How to arrange the CX gates for the Pauli evolutions, can be “chain”, where next neighbor connections are used, or “fountain”, where all qubits are connected to one. +* **atomic\_evolution** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)")*\[\[*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.operators.symplectic.pauli.Pauli") *|*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.operators.symplectic.sparse_pauli_op.SparsePauliOp")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")*] | None*) – A function to construct the circuit for the evolution of single Pauli string. Per default, a single Pauli evolution is decomposed in a CX chain and a single qubit Z rotation. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If order is not even + +## Attributes + + + +### settings + +Return the settings in a dictionary, which can be used to reconstruct the object. + +**Returns** + +A dictionary containing the settings of this product formula. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – If a custom atomic evolution is set, which cannot be serialized. + +## Methods + +### synthesize + + + +`synthesize(evolution)` + +Synthesize an `qiskit.circuit.library.PauliEvolutionGate`. + +**Parameters** + +**evolution** ([*PauliEvolutionGate*](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate")) – The evolution gate to synthesize. + +**Returns** + +A circuit implementing the evolution. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.TwoQubitBasisDecomposer.md b/docs/api/qiskit/0.46/qiskit.synthesis.TwoQubitBasisDecomposer.md new file mode 100644 index 00000000000..d1ee81b4345 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.TwoQubitBasisDecomposer.md @@ -0,0 +1,89 @@ +--- +title: TwoQubitBasisDecomposer +description: API reference for qiskit.synthesis.TwoQubitBasisDecomposer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.TwoQubitBasisDecomposer +--- + +# TwoQubitBasisDecomposer + + + +`qiskit.synthesis.TwoQubitBasisDecomposer(gate, basis_fidelity=1.0, euler_basis='U', pulse_optimize=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/two_qubit/two_qubit_decompose.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A class for decomposing 2-qubit unitaries into minimal number of uses of a 2-qubit basis gate. + +**Parameters** + +* **gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")) – Two-qubit gate to be used in the KAK decomposition. +* **basis\_fidelity** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Fidelity to be assumed for applications of KAK Gate. Default 1.0. +* **euler\_basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Basis string to be provided to OneQubitEulerDecomposer for 1Q synthesis. Valid options are \[‘ZYZ’, ‘ZXZ’, ‘XYX’, ‘U’, ‘U3’, ‘U1X’, ‘PSX’, ‘ZSX’, ‘RR’]. +* **pulse\_optimize** (*None or* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, try to do decomposition which minimizes local unitaries in between entangling gates. This will raise an exception if an optimal decomposition is not implemented. Currently, only \[\{CX, SX, RZ}] is known. If False, don’t attempt optimization. If None, attempt optimization but don’t raise if unknown. + +## Methods + +### decomp0 + + + +`static decomp0(target)` + +Decompose target \~Ud(x, y, z) with 0 uses of the basis gate. Result Ur has trace: $|Tr(Ur.Utarget^dag)| = 4|(cos(x)cos(y)cos(z)+ j sin(x)sin(y)sin(z)|$, which is optimal for all targets and bases + +### decomp1 + + + +`decomp1(target)` + +Decompose target \~Ud(x, y, z) with 1 uses of the basis gate \~Ud(a, b, c). Result Ur has trace: .. math: + +```python +|Tr(Ur.Utarget^dag)| = 4|cos(x-a)cos(y-b)cos(z-c) + j sin(x-a)sin(y-b)sin(z-c)| +``` + +which is optimal for all targets and bases with z==0 or c==0 + +### decomp2\_supercontrolled + + + +`decomp2_supercontrolled(target)` + +Decompose target \~Ud(x, y, z) with 2 uses of the basis gate. + +For supercontrolled basis \~Ud(pi/4, b, 0), all b, result Ur has trace .. math: + +```python +|Tr(Ur.Utarget^dag)| = 4cos(z) +``` + +which is the optimal approximation for basis of CNOT-class `~Ud(pi/4, 0, 0)` or DCNOT-class `~Ud(pi/4, pi/4, 0)` and any target. May be sub-optimal for b!=0 (e.g. there exists exact decomposition for any target using B `B~Ud(pi/4, pi/8, 0)`, but not this decomposition.) This is an exact decomposition for supercontrolled basis and target `~Ud(x, y, 0)`. No guarantees for non-supercontrolled basis. + +### decomp3\_supercontrolled + + + +`decomp3_supercontrolled(target)` + +Decompose target with 3 uses of the basis. This is an exact decomposition for supercontrolled basis \~Ud(pi/4, b, 0), all b, and any target. No guarantees for non-supercontrolled basis. + +### num\_basis\_gates + + + +`num_basis_gates(unitary)` + +Computes the number of basis gates needed in a decomposition of input unitary + +### traces + + + +`traces(target)` + +Give the expected traces $|Tr(U \cdot Utarget^dag)|$ for different number of basis gates. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.XXDecomposer.md b/docs/api/qiskit/0.46/qiskit.synthesis.XXDecomposer.md new file mode 100644 index 00000000000..1e5bfa6e0f8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.XXDecomposer.md @@ -0,0 +1,41 @@ +--- +title: XXDecomposer +description: API reference for qiskit.synthesis.XXDecomposer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.XXDecomposer +--- + +# XXDecomposer + + + +`qiskit.synthesis.XXDecomposer(basis_fidelity=1.0, euler_basis='U', embodiments=None, backup_optimizer=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/two_qubit/xx_decompose/decomposer.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A class for optimal decomposition of 2-qubit unitaries into 2-qubit basis gates of XX type (i.e., each locally equivalent to CAN(alpha, 0, 0) for a possibly varying alpha). + +**Parameters** + +* **basis\_fidelity** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – available strengths and fidelity of each. Can be either (1) a dictionary mapping XX angle values to fidelity at that angle; or (2) a single float f, interpreted as \{pi: f, pi/2: f/2, pi/3: f/3}. +* **euler\_basis** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Basis string provided to OneQubitEulerDecomposer for 1Q synthesis. Defaults to “U”. +* **embodiments** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*,* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – A dictionary mapping interaction strengths alpha to native circuits which embody the gate CAN(alpha, 0, 0). Strengths are taken so that pi/2 represents the class of a full CX. +* **backup\_optimizer** (*Callable\[...,* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – If supplied, defers synthesis to this callable when XXDecomposer has no efficient decomposition of its own. Useful for special cases involving 2 or 3 applications of XX(pi/2), in which case standard synthesis methods provide lower 1Q gate count. + + + If `embodiments` is not passed, or if an entry is missing, it will be populated as needed using the method `_default_embodiment`. + + +## Methods + +### num\_basis\_gates + + + +`num_basis_gates(unitary)` + +Counts the number of gates that would be emitted during re-synthesis. + +NOTE: Used by ConsolidateBlocks. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.AQC.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.AQC.md new file mode 100644 index 00000000000..bb201f84f14 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.AQC.md @@ -0,0 +1,49 @@ +--- +title: AQC +description: API reference for qiskit.synthesis.unitary.aqc.AQC +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.AQC +--- + +# AQC + + + +`qiskit.synthesis.unitary.aqc.AQC(optimizer=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/aqc.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A generic implementation of the Approximate Quantum Compiler. This implementation is agnostic of the underlying implementation of the approximate circuit, objective, and optimizer. Users may pass corresponding implementations of the abstract classes: + +* The *optimizer* is an implementation of the [`Minimizer`](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") protocol, a callable used to run the optimization process. The choice of optimizer may affect overall convergence, required time for the optimization process and achieved objective value. +* The *approximate circuit* represents a template which parameters we want to optimize. Currently, there’s only one implementation based on 4-rotations CNOT unit blocks: [`CNOTUnitCircuit`](qiskit.synthesis.unitary.aqc.CNOTUnitCircuit "qiskit.synthesis.unitary.aqc.CNOTUnitCircuit"). See the paper for more details. +* The *approximate objective* is tightly coupled with the approximate circuit implementation and provides two methods for computing objective function and gradient with respect to approximate circuit parameters. This objective is passed to the optimizer. Currently, there are two implementations based on 4-rotations CNOT unit blocks: [`DefaultCNOTUnitObjective`](qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective "qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective") and its accelerated version [`FastCNOTUnitObjective`](qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective "qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective"). Both implementations share the same idea of maximization the Hilbert-Schmidt product between the target matrix and its approximation. The former implementation approach should be considered as a baseline one. It may suffer from performance issues, and is mostly suitable for a small number of qubits (up to 5 or 6), whereas the latter, accelerated one, can be applied to larger problems. +* One should take into consideration the exponential growth of matrix size with the number of qubits because the implementation not only creates a potentially large target matrix, but also allocates a number of temporary memory buffers comparable in size to the target matrix. + + + Setting the optimizer argument to an instance of qiskit.algorithms.optimizers.Optimizer is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. Please, submit a callable that follows the Minimizer protocol instead. + + +**Parameters** + +* **optimizer** ([*Minimizer*](qiskit.algorithms.optimizers.Minimizer "qiskit.algorithms.optimizers.Minimizer") *|*[*Optimizer*](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") *| None*) – an optimizer to be used in the optimization procedure of the search for the best approximate circuit. By default, the scipy minimizer with the `L-BFGS-B` method is used with max iterations set to 1000. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – a seed value to be used by a random number generator. + +## Methods + +### compile\_unitary + + + +`compile_unitary(target_matrix, approximate_circuit, approximating_objective, initial_point=None)` + +Approximately compiles a circuit represented as a unitary matrix by solving an optimization problem defined by `approximating_objective` and using `approximate_circuit` as a template for the approximate circuit. + +**Parameters** + +* **target\_matrix** (*np.ndarray*) – a unitary matrix to approximate. +* **approximate\_circuit** ([*ApproximateCircuit*](qiskit.synthesis.unitary.aqc.ApproximateCircuit "qiskit.synthesis.unitary.aqc.ApproximateCircuit")) – a template circuit that will be filled with the parameter values obtained in the optimization procedure. +* **approximating\_objective** ([*ApproximatingObjective*](qiskit.synthesis.unitary.aqc.ApproximatingObjective "qiskit.synthesis.unitary.aqc.ApproximatingObjective")) – a definition of the optimization problem. +* **initial\_point** (*np.ndarray | None*) – initial values of angles/parameters to start optimization from. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md new file mode 100644 index 00000000000..926e2370bfe --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximateCircuit.md @@ -0,0 +1,240 @@ +--- +title: ApproximateCircuit +description: API reference for qiskit.synthesis.unitary.aqc.ApproximateCircuit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.ApproximateCircuit +--- + +# ApproximateCircuit + + + +`qiskit.synthesis.unitary.aqc.ApproximateCircuit(num_qubits, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/approximate.py "view source code") + +Bases: [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +A base class that represents an approximate circuit. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubit this circuit will span. +* **name** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – a name of the circuit. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### thetas + +The property is not implemented and raises a `NotImplementedException` exception. + +**Returns** + +a vector of parameters of this circuit. + +## Methods + +### build + + + +`abstract build(thetas)` + +**Constructs this circuit out of the parameters(thetas). Parameter values must be set before** + +constructing the circuit. + +**Parameters** + +**thetas** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a vector of parameters to be set in this circuit. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md new file mode 100644 index 00000000000..6fb56ec00a0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.ApproximatingObjective.md @@ -0,0 +1,74 @@ +--- +title: ApproximatingObjective +description: API reference for qiskit.synthesis.unitary.aqc.ApproximatingObjective +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.ApproximatingObjective +--- + +# ApproximatingObjective + + + +`qiskit.synthesis.unitary.aqc.ApproximatingObjective`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/approximate.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +A base class for an optimization problem definition. An implementing class must provide at least an implementation of the `objective` method. In such case only gradient free optimizers can be used. Both method, `objective` and `gradient`, preferable to have in an implementation. + +## Attributes + + + +### num\_thetas + +Returns: the number of parameters in this optimization problem. + + + +### target\_matrix + +Returns: a matrix being approximated + +## Methods + +### gradient + + + +`abstract gradient(param_values)` + +Computes a gradient with respect to parameters given a vector of parameter values. + +**Parameters** + +**param\_values** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a vector of parameter values for the optimization problem. + +**Returns** + +an array of gradient values. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### objective + + + +`abstract objective(param_values)` + +Computes a value of the objective function given a vector of parameter values. + +**Parameters** + +**param\_values** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a vector of parameter values for the optimization problem. + +**Returns** + +a float value of the objective function. + +**Return type** + +[*SupportsFloat*](https://docs.python.org/3/library/typing.html#typing.SupportsFloat "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md new file mode 100644 index 00000000000..86133578291 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitCircuit.md @@ -0,0 +1,242 @@ +--- +title: CNOTUnitCircuit +description: API reference for qiskit.synthesis.unitary.aqc.CNOTUnitCircuit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.CNOTUnitCircuit +--- + +# CNOTUnitCircuit + + + +`qiskit.synthesis.unitary.aqc.CNOTUnitCircuit(num_qubits, cnots, tol=0.0, name=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/cnot_unit_circuit.py "view source code") + +Bases: [`ApproximateCircuit`](qiskit.synthesis.unitary.aqc.ApproximateCircuit "qiskit.synthesis.unitary.aqc.approximate.ApproximateCircuit") + +A class that represents an approximate circuit based on CNOT unit blocks. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits in this circuit. +* **cnots** (*np.ndarray*) – an array of dimensions `(2, L)` indicating where the CNOT units will be placed. +* **tol** (*Optional\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – angle parameter less or equal this (small) value is considered equal zero and corresponding gate is not inserted into the output circuit (because it becomes identity one in this case). +* **name** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – name of this circuit + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if an unsupported parameter is passed. + +## Attributes + + + +### ancillas + +Returns a list of ancilla bits in the order that the registers were added. + + + +### calibrations + +Return calibration dictionary. + +The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}` + + + +### clbits + +Returns a list of classical bits in the order that the registers were added. + + + +### data + +Return the circuit data (instructions and context). + +**Returns** + +a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction. + +**Return type** + +QuantumCircuitData + + + +### extension\_lib + +`= 'include "qelib1.inc";'` + + + +### global\_phase + +Return the global phase of the current circuit scope in radians. + + + +### header + +`= 'OPENQASM 2.0;'` + + + +### instances + +`= 159` + + + +### layout + +Return any associated layout information about the circuit + +This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation. + +There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing. + + + +### metadata + +The user provided metadata associated with the circuit. + +The metadata for the circuit is a user provided `dict` of metadata for the circuit. It will not be used to influence the execution or operation of the circuit, but it is expected to be passed between all transforms of the circuit (ie transpilation) and that providers will associate any circuit metadata with the results it returns from execution of that circuit. + + + +### num\_ancillas + +Return the number of ancilla qubits. + + + +### num\_clbits + +Return number of classical bits. + + + +### num\_parameters + +The number of parameter objects in the circuit. + + + +### num\_qubits + +Return number of qubits. + + + +### op\_start\_times + +Return a list of operation start times. + +This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit. + +**Returns** + +List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`. + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – When circuit is not scheduled. + + + +### parameters + +The parameters defined in the circuit. + +This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically. + +**Examples** + +The snippet below shows that insertion order of parameters does not matter. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant") +>>> circuit = QuantumCircuit(1) +>>> circuit.rx(b, 0) +>>> circuit.rz(elephant, 0) +>>> circuit.ry(a, 0) +>>> circuit.parameters # sorted alphabetically! +ParameterView([Parameter(a), Parameter(b), Parameter(elephant)]) +``` + +Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting. + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter +>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")] +>>> circuit = QuantumCircuit(1) +>>> circuit.u(*angles, 0) +>>> circuit.draw() + ┌─────────────────────────────┐ +q: ┤ U(angle_1,angle_2,angle_10) ├ + └─────────────────────────────┘ +>>> circuit.parameters +ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)]) +``` + +To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used. + +```python +``` + +```python +>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector +>>> x = ParameterVector("x", 12) +>>> circuit = QuantumCircuit(1) +>>> for x_i in x: +... circuit.rx(x_i, 0) +>>> circuit.parameters +ParameterView([ + ParameterVectorElement(x[0]), ParameterVectorElement(x[1]), + ParameterVectorElement(x[2]), ParameterVectorElement(x[3]), + ..., ParameterVectorElement(x[11]) +]) +``` + +**Returns** + +The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit. + + + +### prefix + +`= 'circuit'` + + + +### qubits + +Returns a list of quantum bits in the order that the registers were added. + + + +### thetas + +Returns a vector of rotation angles used by CNOT units in this circuit. + +**Returns** + +Parameters of the rotation gates in this circuit. + +## Methods + +### build + + + +`build(thetas)` + +**Constructs a Qiskit quantum circuit out of the parameters (angles) of this circuit. If a** + +parameter value is less in absolute value than the specified tolerance then the corresponding rotation gate will be skipped in the circuit. + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md new file mode 100644 index 00000000000..c9aa658137f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.CNOTUnitObjective.md @@ -0,0 +1,43 @@ +--- +title: CNOTUnitObjective +description: API reference for qiskit.synthesis.unitary.aqc.CNOTUnitObjective +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.CNOTUnitObjective +--- + +# CNOTUnitObjective + + + +`qiskit.synthesis.unitary.aqc.CNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/cnot_unit_objective.py "view source code") + +Bases: [`ApproximatingObjective`](qiskit.synthesis.unitary.aqc.ApproximatingObjective "qiskit.synthesis.unitary.aqc.approximate.ApproximatingObjective"), [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +A base class for a problem definition based on CNOT unit. This class may have different subclasses for objective and gradient computations. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **cnots** (*np.ndarray*) – a CNOT structure to be used in the optimization procedure. + +## Attributes + + + +### num\_cnots + +Returns: A number of CNOT units to be used by the approximate circuit. + + + +### num\_thetas + +Returns: Number of parameters (angles) of rotation gates in this circuit. + + + +### target\_matrix + +Returns: a matrix being approximated + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md new file mode 100644 index 00000000000..6065f3509f5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective.md @@ -0,0 +1,85 @@ +--- +title: DefaultCNOTUnitObjective +description: API reference for qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective +--- + +# DefaultCNOTUnitObjective + + + +`qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/cnot_unit_objective.py "view source code") + +Bases: [`CNOTUnitObjective`](qiskit.synthesis.unitary.aqc.CNOTUnitObjective "qiskit.synthesis.unitary.aqc.cnot_unit_objective.CNOTUnitObjective") + +A naive implementation of the objective function based on CNOT units. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **cnots** (*np.ndarray*) – a CNOT structure to be used in the optimization procedure. + +## Attributes + + + +### num\_cnots + +Returns: A number of CNOT units to be used by the approximate circuit. + + + +### num\_thetas + +Returns: Number of parameters (angles) of rotation gates in this circuit. + + + +### target\_matrix + +Returns: a matrix being approximated + +## Methods + +### gradient + + + +`gradient(param_values)` + +Computes a gradient with respect to parameters given a vector of parameter values. + +**Parameters** + +**param\_values** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a vector of parameter values for the optimization problem. + +**Returns** + +an array of gradient values. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### objective + + + +`objective(param_values)` + +Computes a value of the objective function given a vector of parameter values. + +**Parameters** + +**param\_values** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a vector of parameter values for the optimization problem. + +**Returns** + +a float value of the objective function. + +**Return type** + +[*SupportsFloat*](https://docs.python.org/3/library/typing.html#typing.SupportsFloat "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md new file mode 100644 index 00000000000..54c624849c8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective.md @@ -0,0 +1,69 @@ +--- +title: FastCNOTUnitObjective +description: API reference for qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective +--- + +# FastCNOTUnitObjective + + + +`qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective(num_qubits, cnots)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/fast_gradient/fast_gradient.py "view source code") + +Bases: [`CNOTUnitObjective`](qiskit.synthesis.unitary.aqc.CNOTUnitObjective "qiskit.synthesis.unitary.aqc.cnot_unit_objective.CNOTUnitObjective") + +Implementation of objective function and gradient calculator, which is similar to `DefaultCNOTUnitObjective` but several times faster. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **cnots** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a CNOT structure to be used in the optimization procedure. + +## Attributes + + + +### num\_cnots + +Returns: A number of CNOT units to be used by the approximate circuit. + + + +### num\_thetas + +Returns: Number of parameters (angles) of rotation gates in this circuit. + + + +### target\_matrix + +Returns: a matrix being approximated + +## Methods + +### gradient + + + +`gradient(param_values)` + +Computes the gradient of objective function. See description of the base class method. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +### objective + + + +`objective(param_values)` + +Computes the objective function and some intermediate data for the subsequent gradient computation. See description of the base class method. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.AnalysisPass.md b/docs/api/qiskit/0.46/qiskit.transpiler.AnalysisPass.md new file mode 100644 index 00000000000..326e3ef21ed --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.AnalysisPass.md @@ -0,0 +1,109 @@ +--- +title: AnalysisPass +description: API reference for qiskit.transpiler.AnalysisPass +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.AnalysisPass +--- + +# AnalysisPass + + + +`qiskit.transpiler.AnalysisPass(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/basepasses.py "view source code") + +Bases: `BasePass` + +An analysis pass: change property set, not DAG. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`abstract run(dag)` + +Run a pass on the DAGCircuit. This is implemented by the pass developer. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – the dag on which the pass is run. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – when this is left unimplemented for a pass. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.CouplingMap.md b/docs/api/qiskit/0.46/qiskit.transpiler.CouplingMap.md new file mode 100644 index 00000000000..b17f0563e20 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.CouplingMap.md @@ -0,0 +1,426 @@ +--- +title: CouplingMap +description: API reference for qiskit.transpiler.CouplingMap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.CouplingMap +--- + +# CouplingMap + + + +`qiskit.transpiler.CouplingMap(couplinglist=None, description=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/coupling.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Directed graph specifying fixed coupling. + +Nodes correspond to physical qubits (integers) and directed edges correspond to permitted CNOT gates, with source and destination corresponding to control and target qubits, respectively. + +Create coupling graph. By default, the generated coupling has no nodes. + +**Parameters** + +* **couplinglist** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or None*) – An initial coupling graph, specified as an adjacency list containing couplings, e.g. \[\[0,1], \[0,2], \[1,2]]. It is required that nodes are contiguously indexed starting at 0. Missed nodes will be added as isolated nodes in the coupling map. +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A string to describe the coupling map. + +## Attributes + + + +### description + + + +### graph + + + +### distance\_matrix + +Return the distance matrix for the coupling map. + +For any qubits where there isn’t a path available between them the value in this position of the distance matrix will be `math.inf`. + + + +### is\_symmetric + +Test if the graph is symmetric. + +Return True if symmetric, False otherwise + + + +### physical\_qubits + +Returns a sorted list of physical\_qubits + +## Methods + +### add\_edge + + + +`add_edge(src, dst)` + +Add directed edge to coupling graph. + +src (int): source physical qubit dst (int): destination physical qubit + +### add\_physical\_qubit + + + +`add_physical_qubit(physical_qubit)` + +Add a physical qubit to the coupling graph as a node. + +physical\_qubit (int): An integer representing a physical qubit. + +**Raises** + +[**CouplingError**](transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – if trying to add duplicate qubit + +### compute\_distance\_matrix + + + +`compute_distance_matrix()` + +Compute the full distance matrix on pairs of nodes. + +The distance map self.\_dist\_matrix is computed from the graph using all\_pairs\_shortest\_path\_length. This is normally handled internally by the [`distance_matrix`](#qiskit.transpiler.CouplingMap.distance_matrix "qiskit.transpiler.CouplingMap.distance_matrix") attribute or the [`distance()`](#qiskit.transpiler.CouplingMap.distance "qiskit.transpiler.CouplingMap.distance") method but can be called if you’re accessing the distance matrix outside of those or want to pre-generate it. + +### connected\_components + + + +`connected_components()` + +Separate a [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") into subgraph [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") for each connected component. + +The connected components of a [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") are the subgraphs that are not part of any larger subgraph. For example, if you had a coupling map that looked like: + +```python +0 --> 1 4 --> 5 ---> 6 --> 7 +| | +| | +V V +2 --> 3 +``` + +then the connected components of that graph are the subgraphs: + +```python +0 --> 1 +| | +| | +V V +2 --> 3 +``` + +and: + +```python +4 --> 5 ---> 6 --> 7 +``` + +For a connected [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object there is only a single connected component, the entire [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap"). + +This method will return a list of [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") objects, one for each connected component in this [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap"). The data payload of each node in the [`graph`](#qiskit.transpiler.CouplingMap.graph "qiskit.transpiler.CouplingMap.graph") attribute will contain the qubit number in the original graph. This will enables mapping the qubit index in a component subgraph to the original qubit in the combined [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap"). For example: + +```python +from qiskit.transpiler import CouplingMap + +cmap = CouplingMap([[0, 1], [1, 2], [2, 0], [3, 4], [4, 5], [5, 3]]) +component_cmaps = cmap.connected_components() +print(component_cmaps[1].graph[0]) +``` + +will print `3` as index `0` in the second component is qubit 3 in the original cmap. + +**Returns** + +**A list of [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") objects for each connected** + +components. The order of this list is deterministic but implementation specific and shouldn’t be relied upon as part of the API. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +### distance + + + +`distance(physical_qubit1, physical_qubit2)` + +Returns the undirected distance between physical\_qubit1 and physical\_qubit2. + +**Parameters** + +* **physical\_qubit1** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – A physical qubit +* **physical\_qubit2** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Another physical qubit + +**Returns** + +The undirected distance + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +**Raises** + +[**CouplingError**](transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – if the qubits do not exist in the CouplingMap + +### draw + + + +`draw()` + +Draws the coupling map. + +This function calls the [`graphviz_draw()`](https://www.rustworkx.org/apiref/rustworkx.visualization.graphviz_draw.html#rustworkx.visualization.graphviz_draw "(in rustworkx v0.14.0)") function from the `rustworkx` package to draw the [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object. + +**Returns** + +Drawn coupling map. + +**Return type** + +PIL.Image + +### from\_full + + + +`classmethod from_full(num_qubits, bidirectional=True)` + +Return a fully connected coupling map on n qubits. + +**Return type** + +[*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") + +### from\_grid + + + +`classmethod from_grid(num_rows, num_columns, bidirectional=True)` + +Return a coupling map of qubits connected on a grid of num\_rows x num\_columns. + +**Return type** + +[*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") + +### from\_heavy\_hex + + + +`classmethod from_heavy_hex(distance, bidirectional=True)` + +Return a heavy hexagon graph coupling map. + +A heavy hexagon graph is described in: + +[https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022](https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022) + +**Parameters** + +* **distance** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The code distance for the generated heavy hex graph. The value for distance can be any odd positive integer. The distance relates to the number of qubits by: $n = \frac{5d^2 - 2d - 1}{2}$ where $n$ is the number of qubits and $d$ is the `distance` parameter. +* **bidirectional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the edges in the output coupling graph are bidirectional or not. By default this is set to `True` + +**Returns** + +A heavy hex coupling graph + +**Return type** + +[CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") + +### from\_heavy\_square + + + +`classmethod from_heavy_square(distance, bidirectional=True)` + +Return a heavy square graph coupling map. + +A heavy square graph is described in: + +[https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022](https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022) + +**Parameters** + +* **distance** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The code distance for the generated heavy square graph. The value for distance can be any odd positive integer. The distance relates to the number of qubits by: $n = 3d^2 - 2d$ where $n$ is the number of qubits and $d$ is the `distance` parameter. +* **bidirectional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the edges in the output coupling graph are bidirectional or not. By default this is set to `True` + +**Returns** + +A heavy square coupling graph + +**Return type** + +[CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") + +### from\_hexagonal\_lattice + + + +`classmethod from_hexagonal_lattice(rows, cols, bidirectional=True)` + +Return a hexagonal lattice graph coupling map. + +**Parameters** + +* **rows** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of rows to generate the graph with. +* **cols** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of columns to generate the graph with. +* **bidirectional** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the edges in the output coupling graph are bidirectional or not. By default this is set to `True` + +**Returns** + +A hexagonal lattice coupling graph + +**Return type** + +[CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") + +### from\_line + + + +`classmethod from_line(num_qubits, bidirectional=True)` + +Return a coupling map of n qubits connected in a line. + +**Return type** + +[*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") + +### from\_ring + + + +`classmethod from_ring(num_qubits, bidirectional=True)` + +Return a coupling map of n qubits connected to each of their neighbors in a ring. + +**Return type** + +[*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") + +### get\_edges + + + +`get_edges()` + +Gets the list of edges in the coupling graph. + +**Returns** + +Each edge is a pair of physical qubits. + +**Return type** + +Tuple([int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)"),[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) + +### is\_connected + + + +`is_connected()` + +Test if the graph is connected. + +Return True if connected, False otherwise + +### largest\_connected\_component + + + +`largest_connected_component()` + +Return a set of qubits in the largest connected component. + +### make\_symmetric + + + +`make_symmetric()` + +Convert uni-directional edges into bi-directional. + +### neighbors + + + +`neighbors(physical_qubit)` + +Return the nearest neighbors of a physical qubit. + +Directionality matters, i.e. a neighbor must be reachable by going one hop in the direction of an edge. + +### reduce + + + +`reduce(mapping, check_if_connected=True)` + +Returns a reduced coupling map that corresponds to the subgraph of qubits selected in the mapping. + +**Parameters** + +* **mapping** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A mapping of reduced qubits to device qubits. +* **check\_if\_connected** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, checks that the reduced coupling map is connected. + +**Returns** + +A reduced coupling\_map for the selected qubits. + +**Return type** + +[CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") + +**Raises** + +[**CouplingError**](transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – Reduced coupling map must be connected. + +### shortest\_undirected\_path + + + +`shortest_undirected_path(physical_qubit1, physical_qubit2)` + +Returns the shortest undirected path between physical\_qubit1 and physical\_qubit2. + +**Parameters** + +* **physical\_qubit1** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – A physical qubit +* **physical\_qubit2** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Another physical qubit + +**Returns** + +The shortest undirected path + +**Return type** + +List + +**Raises** + +[**CouplingError**](transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – When there is no path between physical\_qubit1, physical\_qubit2. + +### size + + + +`size()` + +Return the number of physical qubits in this graph. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.FencedDAGCircuit.md b/docs/api/qiskit/0.46/qiskit.transpiler.FencedDAGCircuit.md new file mode 100644 index 00000000000..bc4cff65e23 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.FencedDAGCircuit.md @@ -0,0 +1,22 @@ +--- +title: FencedDAGCircuit +description: API reference for qiskit.transpiler.FencedDAGCircuit +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.FencedDAGCircuit +--- + +# FencedDAGCircuit + + + +`qiskit.transpiler.FencedDAGCircuit(dag_circuit_instance)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/fencedobjs.py "view source code") + +Bases: `FencedObject` + +A dag circuit that cannot be modified (via remove\_op\_node) + + + The class `qiskit.transpiler.fencedobjs.FencedDAGCircuit` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0 release. Internal use of FencedObject is already removed from pass manager. Implementation of a task subclass with protection for input object modification is now responsibility of the developer. + + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.FencedPropertySet.md b/docs/api/qiskit/0.46/qiskit.transpiler.FencedPropertySet.md new file mode 100644 index 00000000000..d83dd5e8f66 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.FencedPropertySet.md @@ -0,0 +1,22 @@ +--- +title: FencedPropertySet +description: API reference for qiskit.transpiler.FencedPropertySet +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.FencedPropertySet +--- + +# FencedPropertySet + + + +`qiskit.transpiler.FencedPropertySet(property_set_instance)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/fencedobjs.py "view source code") + +Bases: `FencedObject` + +A property set that cannot be written (via \_\_setitem\_\_) + + + The class `qiskit.transpiler.fencedobjs.FencedPropertySet` is deprecated as of qiskit 0.46.0. It will be removed in the 1.0 release. Internal use of FencedObject is already removed from pass manager. Implementation of a task subclass with protection for input object modification is now responsibility of the developer. + + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.InstructionDurations.md b/docs/api/qiskit/0.46/qiskit.transpiler.InstructionDurations.md new file mode 100644 index 00000000000..e97bb79a815 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.InstructionDurations.md @@ -0,0 +1,116 @@ +--- +title: InstructionDurations +description: API reference for qiskit.transpiler.InstructionDurations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.InstructionDurations +--- + +# InstructionDurations + + + +`qiskit.transpiler.InstructionDurations(instruction_durations=None, dt=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/instruction_durations.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Helper class to provide durations of instructions for scheduling. + +It stores durations (gate lengths) and dt to be used at the scheduling stage of transpiling. It can be constructed from `backend` or `instruction_durations`, which is an argument of `transpile()`. The duration of an instruction depends on the instruction (given by name), the qubits, and optionally the parameters of the instruction. Note that these fields are used as keys in dictionaries that are used to retrieve the instruction durations. Therefore, users must use the exact same parameter value to retrieve an instruction duration as the value with which it was added. + +## Methods + +### from\_backend + + + +`classmethod from_backend(backend)` + +Construct an [`InstructionDurations`](#qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") object from the backend. + +**Parameters** + +**backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend")) – backend from which durations (gate lengths) and dt are extracted. + +**Returns** + +The InstructionDurations constructed from backend. + +**Return type** + +[InstructionDurations](#qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If dt and dtm is different in the backend. + +### get + + + +`get(inst, qubits, unit='dt', parameters=None)` + +Get the duration of the instruction with the name, qubits, and parameters. + +Some instructions may have a parameter dependent duration. + +**Parameters** + +* **inst** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – An instruction or its name to be queried. +* **qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – Qubit indices that the instruction acts on. +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. +* **parameters** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*] | None*) – The value of the parameters of the desired instruction. + +**Returns** + +The duration of the instruction on the qubits. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")|[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – No duration is defined for the instruction. + +### units\_used + + + +`units_used()` + +Get the set of all units used in this instruction durations. + +**Returns** + +Set of units used in this instruction durations. + +**Return type** + +[set](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### update + + + +`update(inst_durations, dt=None)` + +Update self with inst\_durations (inst\_durations overwrite self). + +**Parameters** + +* **inst\_durations** (*'InstructionDurationsType' | None*) – Instruction durations to be merged into self (overwriting self). +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Sampling duration in seconds of the target backend. + +**Returns** + +The updated InstructionDurations. + +**Return type** + +[InstructionDurations](#qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the format of instruction\_durations is invalid. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.InstructionProperties.md b/docs/api/qiskit/0.46/qiskit.transpiler.InstructionProperties.md new file mode 100644 index 00000000000..cc076285d7e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.InstructionProperties.md @@ -0,0 +1,52 @@ +--- +title: InstructionProperties +description: API reference for qiskit.transpiler.InstructionProperties +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.InstructionProperties +--- + +# InstructionProperties + + + +`qiskit.transpiler.InstructionProperties(duration=None, error=None, calibration=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/target.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +A representation of the properties of a gate implementation. + +This class provides the optional properties that a backend can provide about an instruction. These represent the set that the transpiler can currently work with if present. However, if your backend provides additional properties for instructions you should subclass this to add additional custom attributes for those custom/additional properties by the backend. + +Create a new `InstructionProperties` object + +**Parameters** + +* **duration** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The duration, in seconds, of the instruction on the specified set of qubits +* **error** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The average error rate for the instruction on the specified set of qubits. +* **calibration** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") *| CalibrationEntry | None*) – The pulse representation of the instruction. + +## Attributes + + + +### duration + + + +### error + + + +### calibration + +The pulse representation of the instruction. + + + This attribute always returns a Qiskit pulse program, but it is internally wrapped by the `CalibrationEntry` to manage unbound parameters and to uniformly handle different data representation, for example, un-parsed Pulse Qobj JSON that a backend provider may provide. + + This value can be overridden through the property setter in following manner. When you set either [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") this is always treated as a user-defined (custom) calibration and the transpiler may automatically attach the calibration data to the output circuit. This calibration data may appear in the wire format as an inline calibration, which may further update the backend standard instruction set architecture. + + If you are a backend provider who provides a default calibration data that is not needed to be attached to the transpiled quantum circuit, you can directly set `CalibrationEntry` instance to this attribute, in which you should set `user_provided=False` when you define calibration data for the entry. End users can still intentionally utilize the calibration data, for example, to run pulse-level simulation of the circuit. However, such entry doesn’t appear in the wire format, and backend must use own definition to compile the circuit down to the execution format. + + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.Layout.md b/docs/api/qiskit/0.46/qiskit.transpiler.Layout.md new file mode 100644 index 00000000000..964fb521c22 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.Layout.md @@ -0,0 +1,267 @@ +--- +title: Layout +description: API reference for qiskit.transpiler.Layout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.Layout +--- + +# Layout + + + +`qiskit.transpiler.Layout(input_dict=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/layout.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Two-ways dict to represent a Layout. + +construct a Layout from a bijective dictionary, mapping virtual qubits to physical qubits + +## Methods + +### add + + + +`add(virtual_bit, physical_bit=None)` + +Adds a map element between bit and physical\_bit. If physical\_bit is not defined, bit will be mapped to a new physical bit. + +**Parameters** + +* **virtual\_bit** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – A (qu)bit. For example, (QuantumRegister(3, ‘qr’), 2). +* **physical\_bit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – A physical bit. For example, 3. + +### add\_register + + + +`add_register(reg)` + +Adds at the end physical\_qubits that map each bit in reg. + +**Parameters** + +**reg** ([*Register*](qiskit.circuit.Register "qiskit.circuit.Register")) – A (qu)bit Register. For example, QuantumRegister(3, ‘qr’). + +### combine\_into\_edge\_map + + + +`combine_into_edge_map(another_layout)` + +Combines self and another\_layout into an “edge map”. + +For example: + +```python + self another_layout resulting edge map +qr_1 -> 0 0 <- q_2 qr_1 -> q_2 +qr_2 -> 2 2 <- q_1 qr_2 -> q_1 +qr_3 -> 3 3 <- q_0 qr_3 -> q_0 +``` + +The edge map is used to compose dags via, for example, compose. + +**Parameters** + +**another\_layout** ([*Layout*](#qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – The other layout to combine. + +**Returns** + +A “edge map”. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – another\_layout can be bigger than self, but not smaller. Otherwise, raises. + +### copy + + + +`copy()` + +Returns a copy of a Layout instance. + +### from\_dict + + + +`from_dict(input_dict)` + +Populates a Layout from a dictionary. + +The dictionary must be a bijective mapping between virtual qubits (tuple) and physical qubits (int). + +**Parameters** + +**input\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + +e.g.: + +```python +{(QuantumRegister(3, 'qr'), 0): 0, + (QuantumRegister(3, 'qr'), 1): 1, + (QuantumRegister(3, 'qr'), 2): 2} + +Can be written more concisely as follows: + +* virtual to physical:: + + {qr[0]: 0, + qr[1]: 1, + qr[2]: 2} + +* physical to virtual:: + + {0: qr[0], + 1: qr[1], + 2: qr[2]} +``` + +### from\_intlist + + + +`static from_intlist(int_list, *qregs)` + +Converts a list of integers to a Layout mapping virtual qubits (index of the list) to physical qubits (the list values). + +**Parameters** + +* **int\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of integers. +* **\*qregs** (*QuantumRegisters*) – The quantum registers to apply the layout to. + +**Returns** + +The corresponding Layout object. + +**Return type** + +[Layout](#qiskit.transpiler.Layout "qiskit.transpiler.Layout") + +**Raises** + +[**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – Invalid input layout. + +### from\_qubit\_list + + + +`static from_qubit_list(qubit_list, *qregs)` + +Populates a Layout from a list containing virtual qubits, Qubit or None. + +**Parameters** + +* **qubit\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – e.g.: \[qr\[0], None, qr\[2], qr\[3]] +* **\*qregs** (*QuantumRegisters*) – The quantum registers to apply the layout to. + +**Returns** + +the corresponding Layout object + +**Return type** + +[Layout](#qiskit.transpiler.Layout "qiskit.transpiler.Layout") + +**Raises** + +[**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – If the elements are not Qubit or None + +### generate\_trivial\_layout + + + +`static generate_trivial_layout(*regs)` + +Creates a trivial (“one-to-one”) Layout with the registers and qubits in regs. + +**Parameters** + +**\*regs** (*Registers, Qubits*) – registers and qubits to include in the layout. + +**Returns** + +A layout with all the regs in the given order. + +**Return type** + +[Layout](#qiskit.transpiler.Layout "qiskit.transpiler.Layout") + +### get\_physical\_bits + + + +`get_physical_bits()` + +Returns the dictionary where the keys are physical (qu)bits and the values are virtual (qu)bits. + +### get\_registers + + + +`get_registers()` + +Returns the registers in the layout \[QuantumRegister(2, ‘qr0’), QuantumRegister(3, ‘qr1’)] :returns: A set of Registers in the layout :rtype: Set + +### get\_virtual\_bits + + + +`get_virtual_bits()` + +Returns the dictionary where the keys are virtual (qu)bits and the values are physical (qu)bits. + +### order\_based\_on\_type + + + +`static order_based_on_type(value1, value2)` + +decides which one is physical/virtual based on the type. Returns (virtual, physical) + +### reorder\_bits + + + +`reorder_bits(bits)` + +Given an ordered list of bits, reorder them according to this layout. + +The list of bits must exactly match the virtual bits in this layout. + +**Parameters** + +**bits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Bit*](qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – the bits to reorder. + +**Returns** + +ordered bits. + +**Return type** + +List + +### swap + + + +`swap(left, right)` + +Swaps the map between left and right. + +**Parameters** + +* **left** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Item to swap with right. +* **right** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Item to swap with left. + +**Raises** + +[**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – If left and right have not the same type. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.PassManager.md b/docs/api/qiskit/0.46/qiskit.transpiler.PassManager.md new file mode 100644 index 00000000000..e9f1ca16c72 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.PassManager.md @@ -0,0 +1,217 @@ +--- +title: PassManager +description: API reference for qiskit.transpiler.PassManager +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.PassManager +--- + +# PassManager + + + +`qiskit.transpiler.PassManager(passes=(), max_iteration=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passmanager.py "view source code") + +Bases: [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.passmanager.BasePassManager") + +Manager for a set of Passes and their scheduling during transpilation. + +Initialize an empty pass manager object. + +**Parameters** + +* **passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A pass set to be added to the pass manager schedule. +* **max\_iteration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of iterations the schedule will be looped if the condition is not met. + +## Methods + +### append + + + +`append(passes, max_iteration=None, **flow_controller_conditions)` + +Append a Pass Set to the schedule of passes. + + + Creating flow controllers with `flow_controller_conditions` keyword arguments was deprecated. Instead, you must explicitly instantiate a controller and set the controller to `passes` argument. + + + + `qiskit.transpiler.passmanager.PassManager.append()`’s argument `max_iteration` is deprecated as of qiskit 0.46. It will be removed in the 1.0 release. ‘max\_iteration’ can be set in the constructor. + + +**Parameters** + +* **passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A set of passes (a pass set) to be added to schedule. A pass set is a list of passes that are controlled by the same flow controller. If a single pass is provided, the pass set will only have that pass a single element. It is also possible to append a `BaseFlowController` instance and the rest of the parameter will be ignored. + +* **max\_iteration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max number of iterations of passes. + +* **flow\_controller\_conditions** (*Any*) – + + Dictionary of control flow plugins. Following built-in controllers are available by default: + + * do\_while: The passes repeat until the callable returns False. Corresponds to [`DoWhileController`](qiskit.passmanager.DoWhileController "qiskit.passmanager.DoWhileController"). + * condition: The passes run only if the callable returns True. Corresponds to [`ConditionalController`](qiskit.passmanager.ConditionalController "qiskit.passmanager.ConditionalController"). + + In general, you have more control simply by creating the controller you want and passing it to [`append()`](#qiskit.transpiler.PassManager.append "qiskit.transpiler.PassManager.append"). + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if a pass in passes is not a proper pass. + +### draw + + + +`draw(filename=None, style=None, raw=False)` + +Draw the pass manager. + +This function needs [pydot](https://github.com/erocarrera/pydot), which in turn needs [Graphviz](https://www.graphviz.org/) to be installed. + +**Parameters** + +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. +* **style** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – keys are the pass classes and the values are the colors to make them. An example can be seen in the DEFAULT\_STYLE. An ordered dict can be used to ensure a priority coloring when pass falls into multiple categories. Any values not included in the provided dict will be filled in from the default dict. +* **raw** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True`, save the raw Dot output instead of the image. + +**Returns** + +an in-memory representation of the pass manager, or `None` if no image was generated or [Pillow](https://pypi.org/project/Pillow/) is not installed. + +**Return type** + +Optional\[[PassManager](#qiskit.transpiler.PassManager "qiskit.transpiler.PassManager")] + +**Raises** + +[**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.12)") – when nxpd or pydot not installed. + +### passes + + + +`passes()` + +Return a list structure of the appended passes and its options. + + + The method `qiskit.transpiler.passmanager.PassManager.passes()` is deprecated as of qiskit 0.46. It will be removed in the 1.0 release. Use .to\_flow\_controller().tasks instead. This returns a sequence of linearized base task instances in tuple format. + + +**Returns** + +A list of pass sets, as defined in `append()`. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), qiskit.transpiler.basepasses.BasePass]] + +### remove + + + +`remove(index)` + +Removes a particular pass in the scheduler. + +**Parameters** + +**index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Pass index to remove, based on the position in [`passes()`](transpiler_passes#module-qiskit.transpiler.passes "qiskit.transpiler.passes"). + +**Raises** + +[**PassManagerError**](passmanager#qiskit.passmanager.PassManagerError "qiskit.passmanager.PassManagerError") – If the index is not found. + +### replace + + + +`replace(index, passes, max_iteration=None, **flow_controller_conditions)` + +Replace a particular pass in the scheduler. + + + Creating flow controllers with `flow_controller_conditions` keyword arguments was deprecated. Instead, you must explicitly instantiate a controller and set the controller to `passes` argument. + + + + `qiskit.transpiler.passmanager.PassManager.replace()`’s argument `max_iteration` is deprecated as of qiskit 0.46. It will be removed in the 1.0 release. ‘max\_iteration’ can be set in the constructor. + + +**Parameters** + +* **index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Pass index to replace, based on the position in passes(). +* **passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A pass set to be added to the pass manager schedule. +* **max\_iteration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max number of iterations of passes. +* **flow\_controller\_conditions** (*Any*) – Dictionary of control flow plugins. See [`qiskit.transpiler.PassManager.append()`](#qiskit.transpiler.PassManager.append "qiskit.transpiler.PassManager.append") for details. + +### run + + + +`run(circuits, output_name=None, callback=None)` + +Run all the passes on the specified `circuits`. + +**Parameters** + +* **circuits** (*\_CircuitsT*) – Circuit(s) to transform via all the registered passes. + +* **output\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The output circuit name. If `None`, it will be set to the same as the input circuit name. + +* **callback** (*Callable*) – + + A callback function that will be called after each pass execution. The function will be called with 5 keyword arguments: + + ```python + pass_ (Pass): the pass being run + dag (DAGCircuit): the dag output of the pass + time (float): the time to execute the pass + property_set (PropertySet): the property set + count (int): the index for the pass execution + ``` + + + Beware that the keyword arguments here are different to those used by the generic [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager"). This pass manager will translate those arguments into the form described above. + + + The exact arguments pass expose the internals of the pass manager and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases be sure to check that the arguments being passed are the same. + + To use the callback feature you define a function that will take in kwargs dict and access the variables. For example: + + ```python + def callback_func(**kwargs): + pass_ = kwargs['pass_'] + dag = kwargs['dag'] + time = kwargs['time'] + property_set = kwargs['property_set'] + count = kwargs['count'] + ... + ``` + +**Returns** + +The transformed circuit(s). + +**Return type** + +\_CircuitsT + +### to\_flow\_controller + + + +`to_flow_controller()` + +Linearize this manager into a single [`FlowControllerLinear`](qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.FlowControllerLinear"), so that it can be nested inside another pass manager. + +**Returns** + +A linearized pass manager. + +**Return type** + +*RunningPassManager* + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.PassManagerConfig.md b/docs/api/qiskit/0.46/qiskit.transpiler.PassManagerConfig.md new file mode 100644 index 00000000000..92dc8eebf0a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.PassManagerConfig.md @@ -0,0 +1,70 @@ +--- +title: PassManagerConfig +description: API reference for qiskit.transpiler.PassManagerConfig +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.PassManagerConfig +--- + +# PassManagerConfig + + + +`qiskit.transpiler.PassManagerConfig(initial_layout=None, basis_gates=None, inst_map=None, coupling_map=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, backend_properties=None, approximation_degree=None, seed_transpiler=None, timing_constraints=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passmanager_config.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Pass Manager Configuration. + +Initialize a PassManagerConfig object + +**Parameters** + +* **initial\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – Initial position of virtual qubits on physical qubits. +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of basis gate names to unroll to. +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")) – Mapping object that maps gate to schedule. +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Directed graph represented a coupling map. +* **layout\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the pass to use for choosing initial qubit placement. This will be the plugin name if an external layout stage plugin is being used. +* **routing\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the pass to use for routing qubits on the architecture. This will be a plugin name if an external routing stage plugin is being used. +* **translation\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the pass to use for translating gates to basis\_gates. This will be a plugin name if an external translation stage plugin is being used. +* **scheduling\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the pass to use for scheduling instructions. This will be a plugin name if an external scheduling stage plugin is being used. +* **instruction\_durations** ([*InstructionDurations*](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations")) – Dictionary of duration (in dt) for each instruction. +* **backend\_properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – Properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. +* **approximation\_degree** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation) +* **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets random seed for the stochastic parts of the transpiler. +* **timing\_constraints** (*TimingConstraints*) – Hardware time alignment restrictions. +* **unitary\_synthesis\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The string method to use for the [`UnitarySynthesis`](qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") pass. Will search installed plugins for a valid method. You can see a list of installed plugins with [`unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names"). +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The backend target +* **hls\_config** (*HLSConfig*) – An optional configuration class to use for [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis") pass. Specifies how to synthesize various high-level objects. +* **init\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The plugin name for the init stage plugin to use +* **optimization\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The plugin name for the optimization stage plugin to use. + +## Methods + +### from\_backend + + + +`classmethod from_backend(backend, _skip_target=False, **pass_manager_options)` + +Construct a configuration based on a backend and user input. + +This method automatically gererates a PassManagerConfig object based on the backend’s features. User options can be used to overwrite the configuration. + +**Parameters** + +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.BackendV1")) – The backend that provides the configuration. +* **pass\_manager\_options** – User-defined option-value pairs. + +**Returns** + +The configuration generated based on the arguments. + +**Return type** + +[PassManagerConfig](#qiskit.transpiler.PassManagerConfig "qiskit.transpiler.PassManagerConfig") + +**Raises** + +[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If the backend does not support a configuration() method. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.StagedPassManager.md b/docs/api/qiskit/0.46/qiskit.transpiler.StagedPassManager.md new file mode 100644 index 00000000000..298d0cd655f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.StagedPassManager.md @@ -0,0 +1,241 @@ +--- +title: StagedPassManager +description: API reference for qiskit.transpiler.StagedPassManager +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.StagedPassManager +--- + +# StagedPassManager + + + +`qiskit.transpiler.StagedPassManager(stages=None, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passmanager.py "view source code") + +Bases: [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.passmanager.PassManager") + +A pass manager pipeline built from individual stages. + +This class enables building a compilation pipeline out of fixed stages. Each `StagedPassManager` defines a list of stages which are executed in a fixed order, and each stage is defined as a standalone [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") instance. There are also `pre_` and `post_` stages for each defined stage. This enables easily composing and replacing different stages and also adding hook points to enable programmatic modifications to a pipeline. When using a staged pass manager you are not able to modify the individual passes and are only able to modify stages. + +By default, instances of `StagedPassManager` define a typical full compilation pipeline from an abstract virtual circuit to one that is optimized and capable of running on the specified backend. The default pre-defined stages are: + +1. `init` - Initial passes to run before embedding the circuit to the backend. +2. `layout` - Maps the virtual qubits in the circuit to the physical qubits on the backend. +3. `routing` - Inserts gates as needed to move the qubit states around until the circuit can be run with the chosen layout on the backend’s coupling map. +4. `translation` - Translates the gates in the circuit to the target backend’s basis gate set. +5. `optimization` - Optimizes the circuit to reduce the cost of executing it. These passes will typically run in a loop until a convergence criteria is met. For example, the convergence criteria might be that the circuit depth does not decrease in successive iterations. +6. `scheduling` - Hardware-aware passes that schedule the operations in the circuit. + + + For backwards compatibility the relative positioning of these default stages will remain stable moving forward. However, new stages may be added to the default stage list in between current stages. For example, in a future release a new phase, something like `logical_optimization`, could be added immediately after the existing `init` stage in the default stage list. This would preserve compatibility for pre-existing `StagedPassManager` users as the relative positions of the stage are preserved so the behavior will not change between releases. + + +These stages will be executed in order and any stage set to `None` will be skipped. If a stage is provided multiple times (i.e. at diferent relative positions), the associated passes, including pre and post, will run once per declaration. If a [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") input is being used for more than 1 stage here (for example in the case of a `Pass` that covers both Layout and Routing) you will want to set that to the earliest stage in sequence that it covers. + +Initialize a new StagedPassManager object + +**Parameters** + +* **stages** (*Iterable\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – An optional list of stages to use for this instance. If this is not specified the default stages list `['init', 'layout', 'routing', 'translation', 'optimization', 'scheduling']` is used. After instantiation, the final list will be immutable and stored as tuple. If a stage is provided multiple times (i.e. at diferent relative positions), the associated passes, including pre and post, will run once per declaration. +* **kwargs** – The initial [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") values for any stages defined in `stages`. If a argument is not defined the stages will default to `None` indicating an empty/undefined stage. + +**Raises** + +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If a stage in the input keyword arguments is not defined. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If an invalid stage name is specified. + +## Attributes + + + +### expanded\_stages + +Expanded Pass manager stages including `pre_` and `post_` phases. + + + +### invalid\_stage\_regex = re.compile('\\\s|\\\\+|\\\\-|\\\\\*|\\\\/|\\\\\\\\|\\\\%|\\\\\<|\\\\>|\\\\@|\\\\!|\\\\\~|\\\\^|\\\\&|\\\\ + +`= re.compile('\\s|\\+|\\-|\\*|\\/|\\\\|\\%|\\<|\\>|\\@|\\!|\\~|\\^|\\&|\\:` + +`= re.compile('\\s|\\+|\\-|\\*|\\/|\\\\|\\%|\\<|\\>|\\@|\\!|\\~|\\^|\\&|\\:|\\[|\\]|\\{|\\}|\\(|\\)')` + + + +### stages + +Pass manager stages + +## Methods + +### append + + + +`append(passes, max_iteration=None, **flow_controller_conditions)` + +Append a Pass Set to the schedule of passes. + + + Creating flow controllers with `flow_controller_conditions` keyword arguments was deprecated. Instead, you must explicitly instantiate a controller and set the controller to `passes` argument. + + + + `qiskit.transpiler.passmanager.PassManager.append()`’s argument `max_iteration` is deprecated as of qiskit 0.46. It will be removed in the 1.0 release. ‘max\_iteration’ can be set in the constructor. + + +**Parameters** + +* **passes** (*Task |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[Task]*) – A set of passes (a pass set) to be added to schedule. A pass set is a list of passes that are controlled by the same flow controller. If a single pass is provided, the pass set will only have that pass a single element. It is also possible to append a `BaseFlowController` instance and the rest of the parameter will be ignored. + +* **max\_iteration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max number of iterations of passes. + +* **flow\_controller\_conditions** (*Any*) – + + Dictionary of control flow plugins. Following built-in controllers are available by default: + + * do\_while: The passes repeat until the callable returns False. Corresponds to [`DoWhileController`](qiskit.passmanager.DoWhileController "qiskit.passmanager.DoWhileController"). + * condition: The passes run only if the callable returns True. Corresponds to [`ConditionalController`](qiskit.passmanager.ConditionalController "qiskit.passmanager.ConditionalController"). + + In general, you have more control simply by creating the controller you want and passing it to [`append()`](#qiskit.transpiler.StagedPassManager.append "qiskit.transpiler.StagedPassManager.append"). + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if a pass in passes is not a proper pass. + +### draw + + + +`draw(filename=None, style=None, raw=False)` + +Draw the staged pass manager. + +### passes + + + +`passes()` + +Return a list structure of the appended passes and its options. + + + The method `qiskit.transpiler.passmanager.PassManager.passes()` is deprecated as of qiskit 0.46. It will be removed in the 1.0 release. Use .to\_flow\_controller().tasks instead. This returns a sequence of linearized base task instances in tuple format. + + +**Returns** + +A list of pass sets, as defined in `append()`. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), qiskit.transpiler.basepasses.BasePass]] + +### remove + + + +`remove(index)` + +Removes a particular pass in the scheduler. + +**Parameters** + +**index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Pass index to remove, based on the position in [`passes()`](transpiler_passes#module-qiskit.transpiler.passes "qiskit.transpiler.passes"). + +**Raises** + +[**PassManagerError**](passmanager#qiskit.passmanager.PassManagerError "qiskit.passmanager.PassManagerError") – If the index is not found. + +### replace + + + +`replace(index, passes, max_iteration=None, **flow_controller_conditions)` + +Replace a particular pass in the scheduler. + + + Creating flow controllers with `flow_controller_conditions` keyword arguments was deprecated. Instead, you must explicitly instantiate a controller and set the controller to `passes` argument. + + + + `qiskit.transpiler.passmanager.PassManager.replace()`’s argument `max_iteration` is deprecated as of qiskit 0.46. It will be removed in the 1.0 release. ‘max\_iteration’ can be set in the constructor. + + +**Parameters** + +* **index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Pass index to replace, based on the position in passes(). +* **passes** (*BasePass |* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[BasePass]*) – A pass set to be added to the pass manager schedule. +* **max\_iteration** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – max number of iterations of passes. +* **flow\_controller\_conditions** (*Any*) – Dictionary of control flow plugins. See [`qiskit.transpiler.PassManager.append()`](qiskit.transpiler.PassManager#append "qiskit.transpiler.PassManager.append") for details. + +### run + + + +`run(circuits, output_name=None, callback=None)` + +Run all the passes on the specified `circuits`. + +**Parameters** + +* **circuits** (*\_CircuitsT*) – Circuit(s) to transform via all the registered passes. + +* **output\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The output circuit name. If `None`, it will be set to the same as the input circuit name. + +* **callback** (*Callable | None*) – + + A callback function that will be called after each pass execution. The function will be called with 5 keyword arguments: + + ```python + pass_ (Pass): the pass being run + dag (DAGCircuit): the dag output of the pass + time (float): the time to execute the pass + property_set (PropertySet): the property set + count (int): the index for the pass execution + ``` + + + Beware that the keyword arguments here are different to those used by the generic [`BasePassManager`](qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager"). This pass manager will translate those arguments into the form described above. + + + The exact arguments pass expose the internals of the pass manager and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases be sure to check that the arguments being passed are the same. + + To use the callback feature you define a function that will take in kwargs dict and access the variables. For example: + + ```python + def callback_func(**kwargs): + pass_ = kwargs['pass_'] + dag = kwargs['dag'] + time = kwargs['time'] + property_set = kwargs['property_set'] + count = kwargs['count'] + ... + ``` + +**Returns** + +The transformed circuit(s). + +**Return type** + +\_CircuitsT + +### to\_flow\_controller + + + +`to_flow_controller()` + +Linearize this manager into a single [`FlowControllerLinear`](qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.FlowControllerLinear"), so that it can be nested inside another pass manager. + +**Returns** + +A linearized pass manager. + +**Return type** + +*RunningPassManager* + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.Target.md b/docs/api/qiskit/0.46/qiskit.transpiler.Target.md new file mode 100644 index 00000000000..445a2c3af39 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.Target.md @@ -0,0 +1,649 @@ +--- +title: Target +description: API reference for qiskit.transpiler.Target +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.Target +--- + +# Target + + + +`qiskit.transpiler.Target(description=None, num_qubits=0, dt=None, granularity=1, min_length=1, pulse_alignment=1, acquire_alignment=1, qubit_properties=None, concurrent_measurements=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/target.py "view source code") + +Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "(in Python v3.12)") + +The intent of the `Target` object is to inform Qiskit’s compiler about the constraints of a particular backend so the compiler can compile an input circuit to something that works and is optimized for a device. It currently contains a description of instructions on a backend and their properties as well as some timing information. However, this exact interface may evolve over time as the needs of the compiler change. These changes will be done in a backwards compatible and controlled manner when they are made (either through versioning, subclassing, or mixins) to add on to the set of information exposed by a target. + +As a basic example, let’s assume backend has two qubits, supports [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate") on both qubits and [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") in both directions. To model this you would create the target like: + +```python +from qiskit.transpiler import Target, InstructionProperties +from qiskit.circuit.library import UGate, CXGate +from qiskit.circuit import Parameter + +gmap = Target() +theta = Parameter('theta') +phi = Parameter('phi') +lam = Parameter('lambda') +u_props = { + (0,): InstructionProperties(duration=5.23e-8, error=0.00038115), + (1,): InstructionProperties(duration=4.52e-8, error=0.00032115), +} +gmap.add_instruction(UGate(theta, phi, lam), u_props) +cx_props = { + (0,1): InstructionProperties(duration=5.23e-7, error=0.00098115), + (1,0): InstructionProperties(duration=4.52e-7, error=0.00132115), +} +gmap.add_instruction(CXGate(), cx_props) +``` + +Each instruction in the `Target` is indexed by a unique string name that uniquely identifies that instance of an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object in the Target. There is a 1:1 mapping between a name and an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instance in the target and each name must be unique. By default, the name is the [`name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") attribute of the instruction, but can be set to anything. This lets a single target have multiple instances of the same instruction class with different parameters. For example, if a backend target has two instances of an [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate") one is parameterized over any theta while the other is tuned up for a theta of pi/6 you can add these by doing something like: + +```python +import math + +from qiskit.transpiler import Target, InstructionProperties +from qiskit.circuit.library import RXGate +from qiskit.circuit import Parameter + +target = Target() +theta = Parameter('theta') +rx_props = { + (0,): InstructionProperties(duration=5.23e-8, error=0.00038115), +} +target.add_instruction(RXGate(theta), rx_props) +rx_30_props = { + (0,): InstructionProperties(duration=1.74e-6, error=.00012) +} +target.add_instruction(RXGate(math.pi / 6), rx_30_props, name='rx_30') +``` + +Then in the `target` object accessing by `rx_30` will get the fixed angle [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate") while `rx` will get the parameterized [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate"). + + + This class assumes that qubit indices start at 0 and are a contiguous set if you want a submapping the bits will need to be reindexed in a new\`\`Target\`\` object. + + + + This class only supports additions of gates, qargs, and qubits. If you need to remove one of these the best option is to iterate over an existing object and create a new subset (or use one of the methods to do this). The object internally caches different views and these would potentially be invalidated by removals. + + +Create a new `Target` object + + + `qiskit.transpiler.target.Target.__init__()`’s argument `aquire_alignment` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. Instead, use the argument `acquire_alignment`, which behaves identically. + + +**Parameters** + +* **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional string to describe the Target. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – An optional int to specify the number of qubits the backend target has. If not set it will be implicitly set based on the qargs when `add_instruction()` is called. Note this must be set if the backend target is for a noiseless simulator that doesn’t have constraints on the instructions so the transpiler knows how many qubits are available. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The system time resolution of input signals in seconds +* **granularity** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – An integer value representing minimum pulse gate resolution in units of `dt`. A user-defined pulse gate should have duration of a multiple of this granularity value. +* **min\_length** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – An integer value representing minimum pulse gate length in units of `dt`. A user-defined pulse gate should be longer than this length. +* **pulse\_alignment** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – An integer value representing a time resolution of gate instruction starting time. Gate instruction should start at time which is a multiple of the alignment value. +* **acquire\_alignment** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at time which is a multiple of the alignment value. +* **qubit\_properties** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of [`QubitProperties`](qiskit.providers.QubitProperties "qiskit.providers.QubitProperties") objects defining the characteristics of each qubit on the target device. If specified the length of this list must match the number of qubits in the target, where the index in the list matches the qubit number the properties are defined for. If some qubits don’t have properties available you can set that entry to `None` +* **concurrent\_measurements** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of sets of qubits that must be measured together. This must be provided as a nested list like `[[0, 1], [2, 3, 4]]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If both `num_qubits` and `qubit_properties` are both defined and the value of `num_qubits` differs from the length of `qubit_properties`. + +## Attributes + + + +### num\_qubits + + + +### description + + + +### dt + + + +### granularity + + + +### min\_length + + + +### pulse\_alignment + + + +### acquire\_alignment + + + +### qubit\_properties + + + +### concurrent\_measurements + + + +### aquire\_alignment + +Alias of deprecated name. This will be removed. + + + The property `qiskit.transpiler.target.Target.aquire_alignment` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. Use the property `acquire_alignment` instead. + + + + +### instructions + +Get the list of tuples ``(:class:`~qiskit.circuit.Instruction`, (qargs))`` for the target + +For globally defined variable width operations the tuple will be of the form `(class, None)` where class is the actual operation class that is globally defined. + + + +### operation\_names + +Get the operation names in the target. + + + +### operations + +Get the operation class objects in the target. + + + +### physical\_qubits + +Returns a sorted list of physical\_qubits + + + +### qargs + +The set of qargs in the target. + +## Methods + +### add\_instruction + + + +`add_instruction(instruction, properties=None, name=None)` + +Add a new instruction to the [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target") + +As `Target` objects are strictly additive this is the primary method for modifying a `Target`. Typically, you will use this to fully populate a `Target` before using it in [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2"). For example: + +```python +from qiskit.circuit.library import CXGate +from qiskit.transpiler import Target, InstructionProperties + +target = Target() +cx_properties = { + (0, 1): None, + (1, 0): None, + (0, 2): None, + (2, 0): None, + (0, 3): None, + (2, 3): None, + (3, 0): None, + (3, 2): None +} +target.add_instruction(CXGate(), cx_properties) +``` + +Will add a [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") to the target with no properties (duration, error, etc) with the coupling edge list: `(0, 1), (1, 0), (0, 2), (2, 0), (0, 3), (2, 3), (3, 0), (3, 2)`. If there are properties available for the instruction you can replace the `None` value in the properties dictionary with an [`InstructionProperties`](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties") object. This pattern is repeated for each [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") the target supports. + +**Parameters** + +* **instruction** ([*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")) – The operation object to add to the map. If it’s parameterized any value of the parameter can be set. Optionally for variable width instructions (such as control flow operations such as `ForLoop` or `MCXGate`) you can specify the class. If the class is specified than the `name` argument must be specified. When a class is used the gate is treated as global and not having any properties set. +* **properties** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – A dictionary of qarg entries to an [`InstructionProperties`](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties") object for that instruction implementation on the backend. Properties are optional for any instruction implementation, if there are no [`InstructionProperties`](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties") available for the backend the value can be None. If there are no constraints on the instruction (as in a noiseless/ideal simulation) this can be set to `{None, None}` which will indicate it runs on all qubits (or all available permutations of qubits for multi-qubit gates). The first `None` indicates it applies to all qubits and the second `None` indicates there are no [`InstructionProperties`](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties") for the instruction. By default, if properties is not set it is equivalent to passing `{None: None}`. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional name to use for identifying the instruction. If not specified the [`name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") attribute of `gate` will be used. All gates in the `Target` need unique names. Backends can differentiate between different parameterization of a single gate by providing a unique name for each (e.g. “rx30”, “rx60”, \`”rx90”\`\` similar to the example in the documentation for the [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target") class). + +**Raises** + +* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.12)") – If gate is already in map +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If an operation class is passed in for `instruction` and no name is specified or `properties` is set. + +### build\_coupling\_map + + + +`build_coupling_map(two_q_gate=None, filter_idle_qubits=False)` + +Get a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") from this target. + +If there is a mix of two qubit operations that have a connectivity constraint and those that are globally defined this will also return `None` because the globally connectivity means there is no constraint on the target. If you wish to see the constraints of the two qubit operations that have constraints you should use the `two_q_gate` argument to limit the output to the gates which have a constraint. + +**Parameters** + +* **two\_q\_gate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional gate name for a two qubit gate in the `Target` to generate the coupling map for. If specified the output coupling map will only have edges between qubits where this gate is present. +* **filter\_idle\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` the output [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") will remove any qubits that don’t have any operations defined in the target. Note that using this argument will result in an output [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object which has holes in its indices which might differ from the assumptions of the class. The typical use case of this argument is to be paired with [`CouplingMap.connected_components()`](qiskit.transpiler.CouplingMap#connected_components "qiskit.transpiler.CouplingMap.connected_components") which will handle the holes as expected. + +**Returns** + +**The [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object** + +for this target. If there are no connectivity constraints in the target this will return `None`. + +**Return type** + +[CouplingMap](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If a non-two qubit gate is passed in for `two_q_gate`. +* [**IndexError**](https://docs.python.org/3/library/exceptions.html#IndexError "(in Python v3.12)") – If an Instruction not in the `Target` is passed in for `two_q_gate`. + +### durations + + + +`durations()` + +Get an InstructionDurations object from the target + +**Returns** + +**The instruction duration represented in the** + +target + +**Return type** + +[InstructionDurations](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") + +### from\_configuration + + + +`classmethod from_configuration(basis_gates, num_qubits=None, coupling_map=None, inst_map=None, backend_properties=None, instruction_durations=None, concurrent_measurements=None, dt=None, timing_constraints=None, custom_name_mapping=None)` + +Create a target object from the individual global configuration + +Prior to the creation of the [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target") class, the constraints of a backend were represented by a collection of different objects which combined represent a subset of the information contained in the [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target"). This function provides a simple interface to convert those separate objects to a [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target"). + +This constructor will use the input from `basis_gates`, `num_qubits`, and `coupling_map` to build a base model of the backend and the `instruction_durations`, `backend_properties`, and `inst_map` inputs are then queried (in that order) based on that model to look up the properties of each instruction and qubit. If there is an inconsistency between the inputs any extra or conflicting information present in `instruction_durations`, `backend_properties`, or `inst_map` will be ignored. + +**Parameters** + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – The list of basis gate names for the backend. For the target to be created these names must either be in the output from `get_standard_gate_name_mapping()` or present in the specified `custom_name_mapping` argument. +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of qubits supported on the backend. +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") *| None*) – The coupling map representing connectivity constraints on the backend. If specified all gates from `basis_gates` will be supported on all qubits (or pairs of qubits). +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") *| None*) – The instruction schedule map representing the pulse [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") definitions for each instruction. If this is specified `coupling_map` must be specified. The `coupling_map` is used as the source of truth for connectivity and if `inst_map` is used the schedule is looked up based on the instructions from the pair of `basis_gates` and `coupling_map`. If you want to define a custom gate for a particular qubit or qubit pair, you can manually build [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target"). +* **backend\_properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") *| None*) – The [`BackendProperties`](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties") object which is used for instruction properties and qubit properties. If specified and instruction properties are intended to be used then the `coupling_map` argument must be specified. This is only used to lookup error rates and durations (unless `instruction_durations` is specified which would take precedence) for instructions specified via `coupling_map` and `basis_gates`. +* **instruction\_durations** ([*InstructionDurations*](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations") *| None*) – Optional instruction durations for instructions. If specified it will take priority for setting the `duration` field in the [`InstructionProperties`](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties") objects for the instructions in the target. +* **concurrent\_measurements** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of sets of qubits that must be measured together. This must be provided as a nested list like `[[0, 1], [2, 3, 4]]`. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – The system time resolution of input signals in seconds +* **timing\_constraints** (*TimingConstraints | None*) – Optional timing constraints to include in the [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target") +* **custom\_name\_mapping** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – An optional dictionary that maps custom gate/operation names in `basis_gates` to an [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") object representing that gate/operation. By default, most standard gates names are mapped to the standard gate object from [`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library") this only needs to be specified if the input `basis_gates` defines gates in names outside that set. + +**Returns** + +the target built from the input configuration + +**Return type** + +[Target](#qiskit.transpiler.Target "qiskit.transpiler.Target") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the input basis gates contain > 2 qubits and `coupling_map` is +* **specified.** – +* [**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.12)") – If no mapping is available for a specified `basis_gate`. + +### get + + + +`get(k[, d]) → D[k] if k in D, else d.  d defaults to None.` + +### get\_calibration + + + +`get_calibration(operation_name, qargs, *args, **kwargs)` + +Get calibrated pulse schedule for the instruction. + +If calibration is templated with parameters, one can also provide those values to build a schedule with assigned parameters. + +**Parameters** + +* **operation\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the operation for the instruction. +* **qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, ...]*) – The tuple of qubit indices for the instruction. +* **args** (*ParameterValueType*) – Parameter values to build schedule if any. +* **kwargs** (*ParameterValueType*) – Parameter values with name to build schedule if any. + +**Returns** + +Calibrated pulse schedule of corresponding instruction. + +**Return type** + +[Schedule](qiskit.pulse.Schedule "qiskit.pulse.Schedule") | [ScheduleBlock](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") + +### get\_non\_global\_operation\_names + + + +`get_non_global_operation_names(strict_direction=False)` + +Return the non-global operation names for the target + +The non-global operations are those in the target which don’t apply on all qubits (for single qubit operations) or all multi-qubit qargs (for multi-qubit operations). + +**Parameters** + +**strict\_direction** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` the multi-qubit operations considered as non-global respect the strict direction (or order of qubits in the qargs is significant). For example, if `cx` is defined on `(0, 1)` and `ecr` is defined over `(1, 0)` by default neither would be considered non-global, but if `strict_direction` is set `True` both `cx` and `ecr` would be returned. + +**Returns** + +A list of operation names for operations that aren’t global in this target + +**Return type** + +List\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### has\_calibration + + + +`has_calibration(operation_name, qargs)` + +Return whether the instruction (operation + qubits) defines a calibration. + +**Parameters** + +* **operation\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the operation for the instruction. +* **qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, ...]*) – The tuple of qubit indices for the instruction. + +**Returns** + +Returns `True` if the calibration is supported and `False` if it isn’t. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### instruction\_properties + + + +`instruction_properties(index)` + +Get the instruction properties for a specific instruction tuple + +This method is to be used in conjunction with the [`instructions`](#qiskit.transpiler.Target.instructions "qiskit.transpiler.Target.instructions") attribute of a [`Target`](#qiskit.transpiler.Target "qiskit.transpiler.Target") object. You can use this method to quickly get the instruction properties for an element of [`instructions`](#qiskit.transpiler.Target.instructions "qiskit.transpiler.Target.instructions") by using the index in that list. However, if you’re not working with [`instructions`](#qiskit.transpiler.Target.instructions "qiskit.transpiler.Target.instructions") directly it is likely more efficient to access the target directly via the name and qubits to get the instruction properties. For example, if [`instructions`](#qiskit.transpiler.Target.instructions "qiskit.transpiler.Target.instructions") returned: + +```python +[(XGate(), (0,)), (XGate(), (1,))] +``` + +you could get the properties of the `XGate` on qubit 1 with: + +```python +props = target.instruction_properties(1) +``` + +but just accessing it directly via the name would be more efficient: + +```python +props = target['x'][(1,)] +``` + +(assuming the `XGate`’s canonical name in the target is `'x'`) This is especially true for larger targets as this will scale worse with the number of instruction tuples in a target. + +**Parameters** + +**index** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The index of the instruction tuple from the [`instructions`](#qiskit.transpiler.Target.instructions "qiskit.transpiler.Target.instructions") attribute. For, example if you want the properties from the third element in [`instructions`](#qiskit.transpiler.Target.instructions "qiskit.transpiler.Target.instructions") you would set this to be `2`. + +**Returns** + +The instruction properties for the specified instruction tuple + +**Return type** + +[InstructionProperties](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties") + +### instruction\_schedule\_map + + + +`instruction_schedule_map()` + +Return an [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") for the instructions in the target with a pulse schedule defined. + +**Returns** + +The instruction schedule map for the instructions in this target with a pulse schedule defined. + +**Return type** + +[InstructionScheduleMap](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap") + +### instruction\_supported + + + +`instruction_supported(operation_name=None, qargs=None, operation_class=None, parameters=None)` + +Return whether the instruction (operation + qubits) is supported by the target + +**Parameters** + +* **operation\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the operation for the instruction. Either this or `operation_class` must be specified, if both are specified `operation_class` will take priority and this argument will be ignored. + +* **qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – The tuple of qubit indices for the instruction. If this is not specified then this method will return `True` if the specified operation is supported on any qubits. The typical application will always have this set (otherwise it’s the same as just checking if the target contains the operation). Normally you would not set this argument if you wanted to check more generally that the target supports an operation with the `parameters` on any qubits. + +* **operation\_class** ([*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*]*) – The operation class to check whether the target supports a particular operation by class rather than by name. This lookup is more expensive as it needs to iterate over all operations in the target instead of just a single lookup. If this is specified it will supersede the `operation_name` argument. The typical use case for this operation is to check whether a specific variant of an operation is supported on the backend. For example, if you wanted to check whether a [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate") was supported on a specific qubit with a fixed angle. That fixed angle variant will typically have a name different from the object’s [`name`](qiskit.circuit.Instruction#name "qiskit.circuit.Instruction.name") attribute (`"rx"`) in the target. This can be used to check if any instances of the class are available in such a case. + +* **parameters** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – + + A list of parameters to check if the target supports them on the specified qubits. If the instruction supports the parameter values specified in the list on the operation and qargs specified this will return `True` but if the parameters are not supported on the specified instruction it will return `False`. If this argument is not specified this method will return `True` if the instruction is supported independent of the instruction parameters. If specified with any [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the list, that entry will be treated as supporting any value, however parameter names will not be checked (for example if an operation in the target is listed as parameterized with `"theta"` and `"phi"` is passed into this function that will return `True`). For example, if called with: + + ```python + parameters = [Parameter("theta")] + target.instruction_supported("rx", (0,), parameters=parameters) + ``` + + will return `True` if an [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate") is supported on qubit 0 that will accept any parameter. If you need to check for a fixed numeric value parameter this argument is typically paired with the `operation_class` argument. For example: + + ```python + target.instruction_supported("rx", (0,), RXGate, parameters=[pi / 4]) + ``` + + will return `True` if an RXGate(pi/4) exists on qubit 0. + +**Returns** + +Returns `True` if the instruction is supported and `False` if it isn’t. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### operation\_from\_name + + + +`operation_from_name(instruction)` + +Get the operation class object for a given name + +**Parameters** + +**instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The instruction name to get the [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instance for + +**Returns** + +The Instruction instance corresponding to the name. This also can also be the class for globally defined variable with operations. + +**Return type** + +[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction") + +### operation\_names\_for\_qargs + + + +`operation_names_for_qargs(qargs)` + +Get the operation names for a specified qargs tuple + +**Parameters** + +**qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – A `qargs` tuple of the qubits to get the gates that apply to it. For example, `(0,)` will return the set of all instructions that apply to qubit 0. If set to `None` this will return the names for any globally defined operations in the target. + +**Returns** + +The set of operation names that apply to the specified `qargs`. + +**Return type** + +[set](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.12)") + +**Raises** + +[**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.12)") – If `qargs` is not in target + +### operations\_for\_qargs + + + +`operations_for_qargs(qargs)` + +Get the operation class object for a specified qargs tuple + +**Parameters** + +**qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – A qargs tuple of the qubits to get the gates that apply to it. For example, `(0,)` will return the set of all instructions that apply to qubit 0. If set to `None` this will return any globally defined operations in the target. + +**Returns** + +The list of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instances that apply to the specified qarg. This may also be a class if a variable width operation is globally defined. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.12)") – If qargs is not in target + +### qargs\_for\_operation\_name + + + +`qargs_for_operation_name(operation)` + +Get the qargs for a given operation name + +**Parameters** + +**operation** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The operation name to get qargs for + +**Returns** + +The set of qargs the gate instance applies to. + +**Return type** + +[set](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.12)") + +### timing\_constraints + + + +`timing_constraints()` + +Get an `TimingConstraints` object from the target + +**Returns** + +The timing constraints represented in the `Target` + +**Return type** + +TimingConstraints + +### update\_from\_instruction\_schedule\_map + + + +`update_from_instruction_schedule_map(inst_map, inst_name_map=None, error_dict=None)` + +Update the target from an instruction schedule map. + +If the input instruction schedule map contains new instructions not in the target they will be added. However, if it contains additional qargs for an existing instruction in the target it will error. + +**Parameters** + +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")) – The instruction + +* **inst\_name\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – An optional dictionary that maps any instruction name in `inst_map` to an instruction object. If not provided, instruction is pulled from the standard Qiskit gates, and finally custom gate instance is created with schedule name. + +* **error\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + A dictionary of errors of the form: + + ```python + {gate_name: {qarg: error}} + ``` + +* **example::** (*for*) – \{‘rx’: \{(0, ): 1.4e-4, (1, ): 1.2e-4}} + +* **defined** (*For each entry in the inst\_map if error\_dict is*) – + +* **from** (*a when updating the Target the error value will be pulled*) – + +* **then** (*this dictionary. If one is not found in error\_dict*) – + +* **used.** (*None will be*) – + +### update\_instruction\_properties + + + +`update_instruction_properties(instruction, qargs, properties)` + +Update the property object for an instruction qarg pair already in the Target + +**Parameters** + +* **instruction** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The instruction name to update +* **qargs** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – The qargs to update the properties of +* **properties** ([*InstructionProperties*](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties")) – The properties to set for this instruction + +**Raises** + +[**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.12)") – If `instruction` or `qarg` are not in the target + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.TransformationPass.md b/docs/api/qiskit/0.46/qiskit.transpiler.TransformationPass.md new file mode 100644 index 00000000000..82de6e3781b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.TransformationPass.md @@ -0,0 +1,109 @@ +--- +title: TransformationPass +description: API reference for qiskit.transpiler.TransformationPass +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.TransformationPass +--- + +# TransformationPass + + + +`qiskit.transpiler.TransformationPass(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/basepasses.py "view source code") + +Bases: `BasePass` + +A transformation pass: change DAG, not property set. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`abstract run(dag)` + +Run a pass on the DAGCircuit. This is implemented by the pass developer. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – the dag on which the pass is run. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – when this is left unimplemented for a pass. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.TranspileLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.TranspileLayout.md new file mode 100644 index 00000000000..0415799654a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.TranspileLayout.md @@ -0,0 +1,234 @@ +--- +title: TranspileLayout +description: API reference for qiskit.transpiler.TranspileLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.TranspileLayout +--- + +# TranspileLayout + + + +`qiskit.transpiler.TranspileLayout(initial_layout, input_qubit_mapping, final_layout=None, _input_qubit_count=None, _output_qubit_list=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/layout.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Layout attributes from output circuit from transpiler. + +The transpiler in general is unitary-perserving up to permutations caused by setting and applying initial layout during the [Layout Stage](transpiler#layout-stage) and [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate") insertion during the [Routing Stage](transpiler#routing-stage). To provide an interface to reason about these permutations caused by the [`transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler"). In general the normal interface to access and reason about the layout transformations made by the transpiler is to use the helper methods defined on this class. + +For example, looking at the initial layout, the transpiler can potentially remap the order of the qubits in your circuit as it fits the circuit to the target backend. If the input circuit was: + +Then during the layout stage the transpiler reorders the qubits to be: + +then the output of the [`initial_virtual_layout()`](#qiskit.transpiler.TranspileLayout.initial_virtual_layout "qiskit.transpiler.TranspileLayout.initial_virtual_layout") would be equivalent to: + +```python +Layout({ + qr[0]: 2, + qr[1]: 1, + qr[2]: 0, +}) +``` + +(it is also this attribute in the [`QuantumCircuit.draw()`](qiskit.circuit.QuantumCircuit#draw "qiskit.circuit.QuantumCircuit.draw") and [`circuit_drawer()`](qiskit.visualization.circuit_drawer "qiskit.visualization.circuit_drawer") which is used to display the mapping of qubits to positions in circuit visualizations post-transpilation) + +Building on this above example for final layout, if the transpiler needed to insert swap gates during routing so the output circuit became: + +then the output of the [`routing_permutation()`](#qiskit.transpiler.TranspileLayout.routing_permutation "qiskit.transpiler.TranspileLayout.routing_permutation") method would be: + +```python +[1, 0, 2] +``` + +which maps the qubits at each position to their final position after any swap insertions caused by routing. + +There are three public attributes associated with the class, however these are mostly provided for backwards compatibility and represent the internal state from the transpiler. They are defined as: + +> * [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout") - This attribute is used to model the permutation caused by the [Layout Stage](transpiler#layout-stage) it contains a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object that maps the input [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")s [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects to the position in the output `QuantumCircuit.qubits` list. +> * [`input_qubit_mapping`](#qiskit.transpiler.TranspileLayout.input_qubit_mapping "qiskit.transpiler.TranspileLayout.input_qubit_mapping") - This attribute is used to retain input ordering of the original [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object. It maps the virtual [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") object from the original circuit (and [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout")) to its corresponding position in [`QuantumCircuit.qubits`](qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") in the original circuit. This is needed when computing the permutation of the `Operator` of the circuit (and used by [`Operator.from_circuit()`](qiskit.quantum_info.Operator#from_circuit "qiskit.quantum_info.Operator.from_circuit")). +> * [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout") - This is a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object used to model the output permutation caused ny any [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted into the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") during the [Routing Stage](transpiler#routing-stage). It maps the output circuit’s qubits from `QuantumCircuit.qubits` in the output circuit to the final position after routing. It is **not** a mapping from the original input circuit’s position to the final position at the end of the transpiled circuit. If you need this you can use the [`final_index_layout()`](#qiskit.transpiler.TranspileLayout.final_index_layout "qiskit.transpiler.TranspileLayout.final_index_layout") to generate this. If this is set to `None` this indicates that routing was not run and it can be considered equivalent to a trivial layout with the qubits from the output circuit’s [`qubits`](qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") list. + +## Attributes + + + +### final\_layout + +`Layout | None` + +`= None` + + + +### initial\_layout + +`Layout` + + + +### input\_qubit\_mapping + +`dict[Qubit, int]` + +## Methods + +### final\_index\_layout + + + +`final_index_layout(filter_ancillas=True)` + +Generate the final layout as an array of integers + +This method will generate an array of final positions for each qubit in the output circuit. For example, if you had an input circuit like: + +```python +qc = QuantumCircuit(3) +qc.h(0) +qc.cx(0, 1) +qc.cx(0, 2) +``` + +and the output from the transpiler was: + +```python +tqc = QuantumCircuit(3) +qc.h(2) +qc.cx(2, 1) +qc.swap(0, 1) +qc.cx(2, 1) +``` + +then the return from this function would be a list of: + +```python +[2, 0, 1] +``` + +because qubit 0 in the original circuit’s final state is on qubit 3 in the output circuit, qubit 1 in the original circuit’s final state is on qubit 0, and qubit 2’s final state is on qubit. The output list length will be as wide as the input circuit’s number of qubits, as the output list from this method is for tracking the permutation of qubits in the original circuit caused by the transpiler. + +**Parameters** + +**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `False` any ancillas allocated in the output circuit will be included in the layout. + +**Returns** + +A list of final positions for each input circuit qubit + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### final\_virtual\_layout + + + +`final_virtual_layout(filter_ancillas=True)` + +Generate the final layout as a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object + +This method will generate an array of final positions for each qubit in the output circuit. For example, if you had an input circuit like: + +```python +qc = QuantumCircuit(3) +qc.h(0) +qc.cx(0, 1) +qc.cx(0, 2) +``` + +and the output from the transpiler was: + +```python +tqc = QuantumCircuit(3) +qc.h(2) +qc.cx(2, 1) +qc.swap(0, 1) +qc.cx(2, 1) +``` + +then the return from this function would be a layout object: + +```python +Layout({ + qc.qubits[0]: 2, + qc.qubits[1]: 0, + qc.qubits[2]: 1, +}) +``` + +because qubit 0 in the original circuit’s final state is on qubit 3 in the output circuit, qubit 1 in the original circuit’s final state is on qubit 0, and qubit 2’s final state is on qubit. The output list length will be as wide as the input circuit’s number of qubits, as the output list from this method is for tracking the permutation of qubits in the original circuit caused by the transpiler. + +**Parameters** + +**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `False` any ancillas allocated in the output circuit will be included in the layout. + +**Returns** + +A layout object mapping to the final positions for each qubit + +**Return type** + +[*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout") + +### initial\_index\_layout + + + +`initial_index_layout(filter_ancillas=False)` + +Generate an initial layout as an array of integers + +**Parameters** + +**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` any ancilla qubits added to the transpiler will not be included in the output. + +**Returns** + +A layout array that maps a position in the array to its new position in the output circuit. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + +### initial\_virtual\_layout + + + +`initial_virtual_layout(filter_ancillas=False)` + +Return a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object for the initial layout. + +This returns a mapping of virtual [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects in the input circuit to the physical qubit selected during layout. This is analogous to the [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout") attribute. + +**Parameters** + +**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` only qubits in the input circuit will be in the returned layout. Any ancilla qubits added to the output circuit will be filtered from the returned object. + +**Returns** + +A layout object mapping the input circuit’s [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects to the selected physical qubits. + +**Return type** + +[*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout") + +### routing\_permutation + + + +`routing_permutation()` + +Generate a final layout as an array of integers + +If there is no [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout") attribute present then that indicates there was no output permutation caused by routing or other transpiler transforms. In this case the function will return a list of `[0, 1, 2, .., n]` to indicate this + +**Returns** + +A layout array that maps a position in the array to its new position in the output circuit + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")] + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPSchedule.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPSchedule.md new file mode 100644 index 00000000000..dea752a400c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPSchedule.md @@ -0,0 +1,130 @@ +--- +title: ALAPSchedule +description: API reference for qiskit.transpiler.passes.ALAPSchedule +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ALAPSchedule +--- + +# ALAPSchedule + + + +`qiskit.transpiler.passes.ALAPSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/alap.py "view source code") + +Bases: `BaseSchedulerTransform` + +ALAP Scheduling pass, which schedules the **stop** time of instructions as late as possible. + +See `BaseSchedulerTransform` for the detailed behavior of the control flow operation, i.e. `c_if`. + + + The class `qiskit.transpiler.passes.scheduling.alap.ALAPSchedule` is pending deprecation as of qiskit 0.21.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use [`ALAPScheduleAnalysis`](qiskit.transpiler.passes.ALAPScheduleAnalysis "qiskit.transpiler.passes.ALAPScheduleAnalysis"), which is an analysis pass that requires a padding pass to later modify the circuit. + + +## Attributes + + + +### CONDITIONAL\_SUPPORTED + +`= (, )` + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ALAPSchedule pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A scheduled DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the circuit is not mapped on physical qubits. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if conditional bit is added to non-supported instruction. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPScheduleAnalysis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPScheduleAnalysis.md new file mode 100644 index 00000000000..d743b2093d3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ALAPScheduleAnalysis.md @@ -0,0 +1,133 @@ +--- +title: ALAPScheduleAnalysis +description: API reference for qiskit.transpiler.passes.ALAPScheduleAnalysis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ALAPScheduleAnalysis +--- + +# ALAPScheduleAnalysis + + + +`qiskit.transpiler.passes.ALAPScheduleAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/scheduling/alap.py "view source code") + +Bases: `BaseScheduler` + +ALAP Scheduling pass, which schedules the **stop** time of instructions as late as possible. + +See the [Scheduling Stage](transpiler#scheduling-stage) section in the [`qiskit.transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler") module documentation for the detailed behavior of the control flow operation, i.e. `c_if`. + +Scheduler initializer. + +**Parameters** + +* **durations** – Durations of instructions to be used in scheduling +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `durations` and this are specified then this argument will take precedence and `durations` will be ignored. + +## Attributes + + + +### CONDITIONAL\_SUPPORTED + +`= (, )` + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ALAPSchedule pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A scheduled DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the circuit is not mapped on physical qubits. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if conditional bit is added to non-supported instruction. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.AQCSynthesisPlugin.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.AQCSynthesisPlugin.md new file mode 100644 index 00000000000..f3e4b6e696a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.AQCSynthesisPlugin.md @@ -0,0 +1,181 @@ +--- +title: AQCSynthesisPlugin +description: API reference for qiskit.transpiler.passes.AQCSynthesisPlugin +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.AQCSynthesisPlugin +--- + +# AQCSynthesisPlugin + + + +`qiskit.transpiler.passes.AQCSynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/aqc_plugin.py "view source code") + +Bases: [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") + +An AQC-based Qiskit unitary synthesis plugin. + +This plugin is invoked by [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") when the `unitary_synthesis_method` parameter is set to `"aqc"`. + +This plugin supports customization and additional parameters can be passed to the plugin by passing a dictionary as the `unitary_synthesis_plugin_config` parameter of the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function. + +Supported parameters in the dictionary: + +**network\_layout (str)** + +Type of network geometry, one of \{`"sequ"`, `"spin"`, `"cart"`, `"cyclic_spin"`, `"cyclic_line"`}. Default value is `"spin"`. + +**connectivity\_type (str)** + +type of inter-qubit connectivity, \{`"full"`, `"line"`, `"star"`}. Default value is `"full"`. + +**depth (int)** + +depth of the CNOT-network, i.e. the number of layers, where each layer consists of a single CNOT-block. + +**optimizer ([`Optimizer`](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer"))** + +An instance of optimizer to be used in the optimization process. + +**seed (int)** + +A random seed. + +**initial\_point ([`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)"))** + +Initial values of angles/parameters to start the optimization process from. + +## Attributes + + + +### max\_qubits + +Maximum number of supported qubits is `14`. + + + +### min\_qubits + +Minimum number of supported qubits is `3`. + + + +### supported\_bases + +The plugin does not support bases for synthesis. + + + +### supports\_basis\_gates + +The plugin does not support basis gates and by default it synthesizes a circuit using `["rx", "ry", "rz", "cx"]` gate basis. + + + +### supports\_coupling\_map + +The plugin does not support coupling maps. + + + +### supports\_gate\_errors + +The plugin does not support gate errors. + + + +### supports\_gate\_errors\_by\_qubit + +Return whether the plugin supports taking `gate_errors_by_qubit` + +This differs from `supports_gate_errors`/`gate_errors` by using a different view of the same data. Instead of being keyed by gate name this is keyed by qubit and uses [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to represent gates (instead of gate names). + +`gate_errors_by_qubit` will be a dictionary in the form of `{(qubits,): [Gate, error]}`. For example: + +```python +{ +(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], +(0, 1): [CXGate(): 0.012012477900732316] +} +``` + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate errors on every gate for each qubit. The gate error rates reported in `gate_errors` are provided by the target device `Backend` object and the exact meaning might be different depending on the backend. + +This defaults to False + + + +### supports\_gate\_lengths + +The plugin does not support gate lengths. + + + +### supports\_gate\_lengths\_by\_qubit + +Return whether the plugin supports taking `gate_lengths_by_qubit` + +This differs from `supports_gate_lengths`/`gate_lengths` by using a different view of the same data. Instead of being keyed by gate name this is keyed by qubit and uses [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to represent gates (instead of gate names) + +`gate_lengths_by_qubit` will be a dictionary in the form of `{(qubits,): [Gate, length]}`. For example: + +```python +{ +(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], +(0, 1): [CXGate(): 0.012012477900732316] +} +``` + +where the `length` value is in units of seconds. + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate lengths on every gate for each qubit. + +This defaults to False + + + +### supports\_natural\_direction + +The plugin does not support natural direction, it assumes bidirectional two qubit gates. + + + +### supports\_pulse\_optimize + +The plugin does not support optimization of pulses. + + + +### supports\_target + +Whether the plugin supports taking `target` as an option + +`target` will be a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the target device for the output of the synthesis pass. + +By default this will be `False` since the plugin interface predates the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class. If a plugin returns `True` for this attribute, it is expected that the plugin will use the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") instead of the values passed if any of `supports_gate_lengths`, `supports_gate_errors`, `supports_coupling_map`, and `supports_basis_gates` are set (although ideally all those parameters should contain duplicate information). + +## Methods + +### run + + + +`run(unitary, **options)` + +Run synthesis for the given unitary matrix + +**Parameters** + +* **unitary** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – The unitary matrix to synthesize to a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object +* **options** – The optional kwargs that are passed based on the output the `support_*` methods on the class. Refer to the documentation for these methods on [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") to see what the keys and values are. + +**Returns** + +The dag circuit representation of the unitary. Alternatively, you can return a tuple of the form `(dag, wires)` where `dag` is the dag circuit representation of the circuit representation of the unitary and `wires` is the mapping wires to use for [`qiskit.dagcircuit.DAGCircuit.substitute_node_with_dag()`](qiskit.dagcircuit.DAGCircuit#substitute_node_with_dag "qiskit.dagcircuit.DAGCircuit.substitute_node_with_dag"). If you return a tuple and `wires` is `None` this will behave just as if only a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") was returned. Additionally if this returns `None` no substitution will be made. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPSchedule.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPSchedule.md new file mode 100644 index 00000000000..803befb9bba --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPSchedule.md @@ -0,0 +1,134 @@ +--- +title: ASAPSchedule +description: API reference for qiskit.transpiler.passes.ASAPSchedule +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ASAPSchedule +--- + +# ASAPSchedule + + + +`qiskit.transpiler.passes.ASAPSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/asap.py "view source code") + +Bases: `BaseSchedulerTransform` + +ASAP Scheduling pass, which schedules the start time of instructions as early as possible.. + +See `BaseSchedulerTransform` for the detailed behavior of the control flow operation, i.e. `c_if`. + + + This base class has been superseded by [`ASAPScheduleAnalysis`](qiskit.transpiler.passes.ASAPScheduleAnalysis "qiskit.transpiler.passes.ASAPScheduleAnalysis") and the new scheduling workflow. It will be deprecated and subsequently removed in a future release. + + + + The class `qiskit.transpiler.passes.scheduling.asap.ASAPSchedule` is pending deprecation as of qiskit 0.21.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use [`ASAPScheduleAnalysis`](qiskit.transpiler.passes.ASAPScheduleAnalysis "qiskit.transpiler.passes.ASAPScheduleAnalysis"), which is an analysis pass that requires a padding pass to later modify the circuit. + + +## Attributes + + + +### CONDITIONAL\_SUPPORTED + +`= (, )` + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ASAPSchedule pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A scheduled DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the circuit is not mapped on physical qubits. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if conditional bit is added to non-supported instruction. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPScheduleAnalysis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPScheduleAnalysis.md new file mode 100644 index 00000000000..e18b8a604d8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ASAPScheduleAnalysis.md @@ -0,0 +1,133 @@ +--- +title: ASAPScheduleAnalysis +description: API reference for qiskit.transpiler.passes.ASAPScheduleAnalysis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ASAPScheduleAnalysis +--- + +# ASAPScheduleAnalysis + + + +`qiskit.transpiler.passes.ASAPScheduleAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/scheduling/asap.py "view source code") + +Bases: `BaseScheduler` + +ASAP Scheduling pass, which schedules the start time of instructions as early as possible. + +See the [Scheduling Stage](transpiler#scheduling-stage) section in the [`qiskit.transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler") module documentation for the detailed behavior of the control flow operation, i.e. `c_if`. + +Scheduler initializer. + +**Parameters** + +* **durations** – Durations of instructions to be used in scheduling +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `durations` and this are specified then this argument will take precedence and `durations` will be ignored. + +## Attributes + + + +### CONDITIONAL\_SUPPORTED + +`= (, )` + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ASAPSchedule pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A scheduled DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the circuit is not mapped on physical qubits. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if conditional bit is added to non-supported instruction. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.AlignMeasures.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.AlignMeasures.md new file mode 100644 index 00000000000..3087553a531 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.AlignMeasures.md @@ -0,0 +1,165 @@ +--- +title: AlignMeasures +description: API reference for qiskit.transpiler.passes.AlignMeasures +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.AlignMeasures +--- + +# AlignMeasures + + + +`qiskit.transpiler.passes.AlignMeasures(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/alignments/align_measures.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Measurement alignment. + +This is a control electronics aware optimization pass. + +In many quantum computing architectures gates (instructions) are implemented with shaped analog stimulus signals. These signals are digitally stored in the waveform memory of the control electronics and converted into analog voltage signals by electronic components called digital to analog converters (DAC). + +In a typical hardware implementation of superconducting quantum processors, a single qubit instruction is implemented by a microwave signal with the duration of around several tens of ns with a per-sample time resolution of \~0.1-10ns, as reported by `backend.configuration().dt`. In such systems requiring higher DAC bandwidth, control electronics often defines a pulse granularity, in other words a data chunk, to allow the DAC to perform the signal conversion in parallel to gain the bandwidth. + +Measurement alignment is required if a backend only allows triggering `measure` instructions at a certain multiple value of this pulse granularity. This value is usually provided by `backend.configuration().timing_constraints`. + +In Qiskit SDK, the duration of delay can take arbitrary value in units of `dt`, thus circuits involving delays may violate the above alignment constraint (i.e. misalignment). This pass shifts measurement instructions to a new time position to fix the misalignment, by inserting extra delay right before the measure instructions. The input of this pass should be scheduled [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit"), thus one should select one of the scheduling passes ([`ALAPSchedule`](qiskit.transpiler.passes.ALAPSchedule "qiskit.transpiler.passes.ALAPSchedule") or `ASAPSchedule`) before calling this. + +**Examples** + +We assume executing the following circuit on a backend with `alignment=16`. + +```python + ┌───┐┌────────────────┐┌─┐ +q_0: ┤ X ├┤ Delay(100[dt]) ├┤M├ + └───┘└────────────────┘└╥┘ +c: 1/════════════════════════╩═ + 0 +``` + +Note that delay of 100 dt induces a misalignment of 4 dt at the measurement. This pass appends an extra 12 dt time shift to the input circuit. + +```python + ┌───┐┌────────────────┐┌─┐ +q_0: ┤ X ├┤ Delay(112[dt]) ├┤M├ + └───┘└────────────────┘└╥┘ +c: 1/════════════════════════╩═ + 0 +``` + +This pass always inserts a positive delay before measurements rather than reducing other delays. + +**Notes** + +The Backend may allow users to execute circuits violating the alignment constraint. However, it may return meaningless measurement data mainly due to the phase error. + +Create new pass. + + + The class `qiskit.transpiler.passes.scheduling.alignments.align_measures.AlignMeasures` is pending deprecation as of qiskit 0.21.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use [`ConstrainedReschedule`](qiskit.transpiler.passes.ConstrainedReschedule "qiskit.transpiler.passes.ConstrainedReschedule"), which performs the same function but also supports aligning to additional timing constraints. + + +**Parameters** + +**alignment** – Integer number representing the minimum time resolution to trigger measure instruction in units of `dt`. This value depends on the control electronics of your quantum processor. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the measurement alignment pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to be checked. + +**Returns** + +DAG with consistent timing and op nodes annotated with duration. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If circuit is not scheduled. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ApplyLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ApplyLayout.md new file mode 100644 index 00000000000..2b9c0b75e3e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ApplyLayout.md @@ -0,0 +1,121 @@ +--- +title: ApplyLayout +description: API reference for qiskit.transpiler.passes.ApplyLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ApplyLayout +--- + +# ApplyLayout + + + +`qiskit.transpiler.passes.ApplyLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/apply_layout.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Transform a circuit with virtual qubits into a circuit with physical qubits. + +Transforms a DAGCircuit with virtual qubits into a DAGCircuit with physical qubits by applying the Layout given in property\_set. Requires either of passes to set/select Layout, e.g. SetLayout, TrivialLayout. Assumes the Layout has full physical qubits. + +If a post layout pass is run and sets the `post_layout` property set field with a new layout to use after `ApplyLayout` has already run once this pass will compact the layouts so that we apply `original_virtual` -> `existing_layout` -> `new_layout` -> `new_physical` so that the output circuit and layout combination become: `original_virtual` -> `new_physical` + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ApplyLayout pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to map. + +**Returns** + +A mapped DAG (with physical qubits). + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if no layout is found in `property_set` or no full physical qubits. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md new file mode 100644 index 00000000000..c9f0f84a8f6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.BarrierBeforeFinalMeasurements.md @@ -0,0 +1,103 @@ +--- +title: BarrierBeforeFinalMeasurements +description: API reference for qiskit.transpiler.passes.BarrierBeforeFinalMeasurements +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.BarrierBeforeFinalMeasurements +--- + +# BarrierBeforeFinalMeasurements + + + +`qiskit.transpiler.passes.BarrierBeforeFinalMeasurements(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/barrier_before_final_measurements.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Add a barrier before final measurements. + +This pass adds a barrier before the set of final measurements. Measurements are considered final if they are followed by no other operations (aside from other measurements or barriers.) + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the BarrierBeforeFinalMeasurements pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.BasicSwap.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.BasicSwap.md new file mode 100644 index 00000000000..52229033d68 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.BasicSwap.md @@ -0,0 +1,127 @@ +--- +title: BasicSwap +description: API reference for qiskit.transpiler.passes.BasicSwap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.BasicSwap +--- + +# BasicSwap + + + +`qiskit.transpiler.passes.BasicSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/routing/basic_swap.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Map (with minimum effort) a DAGCircuit onto a `coupling_map` adding swap gates. + +The basic mapper is a minimum effort to insert swap gates to map the DAG onto a coupling map. When a cx is not in the coupling map possibilities, it inserts one or more swaps in front to make it compatible. + +BasicSwap initializer. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – Directed graph represented a coupling map. +* **fake\_run** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if true, it will only pretend to do routing, i.e., no swap is effectively added. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the BasicSwap pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to map. + +**Returns** + +A mapped DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the coupling map or the layout are not +* **compatible with the DAG**\*\*, or \*\***if the coupling\_map=None.** – + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.BasisTranslator.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.BasisTranslator.md new file mode 100644 index 00000000000..6177675f1f6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.BasisTranslator.md @@ -0,0 +1,172 @@ +--- +title: BasisTranslator +description: API reference for qiskit.transpiler.passes.BasisTranslator +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.BasisTranslator +--- + +# BasisTranslator + + + +`qiskit.transpiler.passes.BasisTranslator(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/basis/basis_translator.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Translates gates to a target basis by searching for a set of translations from a given EquivalenceLibrary. + +This pass operates in several steps: + +* Determine the source basis from the input circuit. +* Perform a Dijkstra search over basis sets, starting from the device’s target\_basis new gates are being generated using the rules from the provided EquivalenceLibrary and the search stops if all gates in the source basis have been generated. +* The found path, as a set of rules from the EquivalenceLibrary, is composed into a set of gate replacement rules. +* The composed replacement rules are applied in-place to each op node which is not already in the target\_basis. + +If the target keyword argument is specified and that [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") objects contains operations which are non-global (i.e. they are defined only for a subset of qubits), as calculated by [`get_non_global_operation_names()`](qiskit.transpiler.Target#get_non_global_operation_names "qiskit.transpiler.Target.get_non_global_operation_names"), this pass will attempt to match the output translation to those constraints. For 1 qubit operations this is straightforward, the pass will perform a search using the union of the set of global operations with the set of operations defined solely on that qubit. For multi-qubit gates this is a bit more involved, while the behavior is initially similar to the single qubit case, just using all the qubits the operation is run on (where order is not significant) isn’t sufficient. We also need to consider any potential local qubits defined on subsets of the quantum arguments for the multi-qubit operation. This means the target used for the search of a non-global multi-qubit gate is the union of global operations, non-global multi-qubit gates sharing the same qubits, and any non-global gates defined on any subset of the qubits used. + + + In the case of non-global operations it is possible for a single execution of this pass to output an incomplete translation if any non-global gates are defined on qubits that are a subset of a larger multi-qubit gate. For example, if you have a `u` gate only defined on qubit 0 and an `x` gate only on qubit 1 it is possible when translating a 2 qubit operation on qubit 0 and 1 that the output might have `u` on qubit 1 and `x` on qubit 0. Typically running this pass a second time will correct these issues. + + + + +## Translation Errors + +This pass will error if there is no path to translate an input gate to the specified basis. However, during a typical/default preset passmanager this pass gets run multiple times at different stages of the compilation pipeline. This means that potentially the input gates that are getting translated were not in the input circuit to [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") as they were generated by an intermediate transform in the circuit. + +When this error occurs it typically means that either the target basis is not universal or there are additional equivalence rules needed in the :clas:\~.EquivalenceLibrary\` instance being used by the :class:\~.BasisTranslator\` pass. You can refer to [Custom Basis Gates](providers#custom-basis-gates) for details on adding custom equivalence rules. + +Initialize a BasisTranslator instance. + +**param equivalence\_library** + +The equivalence library which will be used by the BasisTranslator pass. (Instructions in this library will not be unrolled by this pass.) + +**type equivalence\_library** + +EquivalenceLibrary + +**param target\_basis** + +Target basis names to unroll to, e.g. \[‘u3’, ‘cx’]. + +**type target\_basis** + +list\[str] + +**param target** + +The backend compilation target + +**type target** + +Target + +**param min\_qubits** + +The minimum number of qubits for operations in the input dag to translate. + +**type min\_qubits** + +int + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Translate an input DAGCircuit to the target basis. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – input dag + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the target basis cannot be reached + +**Returns** + +translated circuit. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CSPLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CSPLayout.md new file mode 100644 index 00000000000..1d90d862ef5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CSPLayout.md @@ -0,0 +1,118 @@ +--- +title: CSPLayout +description: API reference for qiskit.transpiler.passes.CSPLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CSPLayout +--- + +# CSPLayout + + + +`qiskit.transpiler.passes.CSPLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/csp_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +If possible, chooses a Layout as a CSP, using backtracking. + +If possible, chooses a Layout as a CSP, using backtracking. + +If not possible, does not set the layout property. In all the cases, the property CSPLayout\_stop\_reason will be added with one of the following values: + +* solution found: If a perfect layout was found. +* nonexistent solution: If no perfect layout was found and every combination was checked. +* call limit reached: If no perfect layout was found and the call limit was reached. +* time limit reached: If no perfect layout was found and the time limit was reached. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – Directed graph representing a coupling map. +* **strict\_direction** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, considers the direction of the coupling map. Default is False. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets the seed of the PRNG. +* **call\_limit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Amount of times that `constraint.RecursiveBacktrackingSolver.recursiveBacktracking` will be called. None means no call limit. Default: 1000. +* **time\_limit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Amount of seconds that the pass will try to find a solution. None means no time limit. Default: 10 seconds. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +run the layout method + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CXCancellation.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CXCancellation.md new file mode 100644 index 00000000000..4e20f47fe1e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CXCancellation.md @@ -0,0 +1,113 @@ +--- +title: CXCancellation +description: API reference for qiskit.transpiler.passes.CXCancellation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CXCancellation +--- + +# CXCancellation + + + +`qiskit.transpiler.passes.CXCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/cx_cancellation.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Cancel back-to-back `cx` gates in dag. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CXCancellation pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the directed acyclic graph to run on. + +**Returns** + +Transformed DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckGateDirection.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckGateDirection.md new file mode 100644 index 00000000000..725054bb616 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckGateDirection.md @@ -0,0 +1,114 @@ +--- +title: CheckGateDirection +description: API reference for qiskit.transpiler.passes.CheckGateDirection +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CheckGateDirection +--- + +# CheckGateDirection + + + +`qiskit.transpiler.passes.CheckGateDirection(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/check_gate_direction.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Check if the two-qubit gates follow the right direction with respect to the coupling map. + +CheckGateDirection initializer. + +**Parameters** + +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Directed graph representing a coupling map. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The backend target to use for this pass. If this is specified it will be used instead of the coupling map + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CheckGateDirection pass on dag. + +If dag is mapped and the direction is correct the property is\_direction\_mapped is set to True (or to False otherwise). + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to check. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckMap.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckMap.md new file mode 100644 index 00000000000..a119b90de02 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CheckMap.md @@ -0,0 +1,116 @@ +--- +title: CheckMap +description: API reference for qiskit.transpiler.passes.CheckMap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CheckMap +--- + +# CheckMap + + + +`qiskit.transpiler.passes.CheckMap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/check_map.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Check if a DAG circuit is already mapped to a coupling map. + +Check if a DAGCircuit is mapped to `coupling_map` by checking that all 2-qubit interactions are laid out to be on adjacent qubits in the global coupling map of the device, setting the property set field (either specified with `property_set_field` or the default `is_swap_mapped`) to `True` or `False` accordingly. Note this does not validate directionality of the connectivity between qubits. If you need to check gates are implemented in a native direction for a target use the [`CheckGateDirection`](qiskit.transpiler.passes.CheckGateDirection "qiskit.transpiler.passes.CheckGateDirection") pass instead. + +CheckMap initializer. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – Directed graph representing a coupling map. +* **property\_set\_field** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – An optional string to specify the property set field to store the result of the check. If not default the result is stored in `"is_swap_mapped"`. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CheckMap pass on dag. + +If dag is mapped to coupling\_map, the property is\_swap\_mapped is set to True (or to False otherwise). + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to map. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect1qRuns.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect1qRuns.md new file mode 100644 index 00000000000..6d0e5dda78b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect1qRuns.md @@ -0,0 +1,105 @@ +--- +title: Collect1qRuns +description: API reference for qiskit.transpiler.passes.Collect1qRuns +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Collect1qRuns +--- + +# Collect1qRuns + + + +`qiskit.transpiler.passes.Collect1qRuns(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/collect_1q_runs.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Collect one-qubit subcircuits. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Collect1qBlocks pass on dag. + +The blocks contain “op” nodes in topological order such that all gates in a block act on the same qubits and are adjacent in the circuit. + +After the execution, `property_set['run_list']` is set to a list of tuples of “op” node. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect2qBlocks.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect2qBlocks.md new file mode 100644 index 00000000000..8f4f6f698b9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Collect2qBlocks.md @@ -0,0 +1,105 @@ +--- +title: Collect2qBlocks +description: API reference for qiskit.transpiler.passes.Collect2qBlocks +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Collect2qBlocks +--- + +# Collect2qBlocks + + + +`qiskit.transpiler.passes.Collect2qBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/collect_2q_blocks.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Collect two-qubit subcircuits. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Collect2qBlocks pass on dag. + +The blocks contain “op” nodes in topological order such that all gates in a block act on the same qubits and are adjacent in the circuit. + +After the execution, `property_set['block_list']` is set to a list of tuples of “op” node. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectCliffords.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectCliffords.md new file mode 100644 index 00000000000..776560a4f0e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectCliffords.md @@ -0,0 +1,119 @@ +--- +title: CollectCliffords +description: API reference for qiskit.transpiler.passes.CollectCliffords +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CollectCliffords +--- + +# CollectCliffords + + + +`qiskit.transpiler.passes.CollectCliffords(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/collect_cliffords.py "view source code") + +Bases: `CollectAndCollapse` + +Collects blocks of Clifford gates and replaces them by a [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") object. + +CollectCliffords initializer. + +**Parameters** + +* **do\_commutative\_analysis** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, exploits commutativity relations between nodes. +* **split\_blocks** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, splits collected blocks into sub-blocks over disjoint qubit subsets. +* **min\_block\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – specifies the minimum number of gates in the block for the block to be collected. +* **split\_layers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, splits collected blocks into sub-blocks over disjoint qubit subsets. +* **collect\_from\_back** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – specifies if blocks should be collected started from the end of the circuit. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CollectLinearFunctions pass on dag. :param dag: the DAG to be optimized. :type dag: DAGCircuit + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectLinearFunctions.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectLinearFunctions.md new file mode 100644 index 00000000000..e1cd3282961 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectLinearFunctions.md @@ -0,0 +1,119 @@ +--- +title: CollectLinearFunctions +description: API reference for qiskit.transpiler.passes.CollectLinearFunctions +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CollectLinearFunctions +--- + +# CollectLinearFunctions + + + +`qiskit.transpiler.passes.CollectLinearFunctions(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/collect_linear_functions.py "view source code") + +Bases: `CollectAndCollapse` + +Collect blocks of linear gates ([`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") and [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate") gates) and replaces them by linear functions ([`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction")). + +CollectLinearFunctions initializer. + +**Parameters** + +* **do\_commutative\_analysis** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, exploits commutativity relations between nodes. +* **split\_blocks** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, splits collected blocks into sub-blocks over disjoint qubit subsets. +* **min\_block\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – specifies the minimum number of gates in the block for the block to be collected. +* **split\_layers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, splits collected blocks into sub-blocks over disjoint qubit subsets. +* **collect\_from\_back** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – specifies if blocks should be collected started from the end of the circuit. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CollectLinearFunctions pass on dag. :param dag: the DAG to be optimized. :type dag: DAGCircuit + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectMultiQBlocks.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectMultiQBlocks.md new file mode 100644 index 00000000000..19d1ff2c242 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CollectMultiQBlocks.md @@ -0,0 +1,133 @@ +--- +title: CollectMultiQBlocks +description: API reference for qiskit.transpiler.passes.CollectMultiQBlocks +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CollectMultiQBlocks +--- + +# CollectMultiQBlocks + + + +`qiskit.transpiler.passes.CollectMultiQBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/collect_multiqubit_blocks.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Collect sequences of uninterrupted gates acting on groups of qubits. `max_block_size` specifies the maximum number of qubits that can be acted upon by any single group of gates + +Traverse the DAG and find blocks of gates that act consecutively on groups of qubits. Write the blocks to `property_set` as a list of blocks of the form: + +```python +[[g0, g1, g2], [g4, g5]] +``` + +Blocks are reported in a valid topological order. Further, the gates within each block are also reported in topological order Some gates may not be present in any block (e.g. if the number of operands is greater than `max_block_size`) + +A Disjoint Set Union data structure (DSU) is used to maintain blocks as gates are processed. This data structure points each qubit to a set at all times and the sets correspond to current blocks. These change over time and the data structure allows these changes to be done quickly. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### find\_set + + + +`find_set(index)` + +DSU function for finding root of set of items If my parent is myself, I am the root. Otherwise we recursively find the root for my parent. After that, we assign my parent to be my root, saving recursion in the future. + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CollectMultiQBlocks pass on dag. + +The blocks contain “op” nodes in topological sort order such that all gates in a block act on the same set of qubits and are adjacent in the circuit. + +The blocks are built by examining predecessors and successors of “cx” gates in the circuit. u1, u2, u3, cx, id gates will be included. + +After the execution, `property_set['block_list']` is set to a list of tuples of `DAGNode` objects + +### union\_set + + + +`union_set(set1, set2)` + +DSU function for unioning two sets together Find the roots of each set. Then assign one to have the other as its parent, thus liking the sets. Merges smaller set into larger set in order to have better runtime + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutationAnalysis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutationAnalysis.md new file mode 100644 index 00000000000..9eec3185624 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutationAnalysis.md @@ -0,0 +1,105 @@ +--- +title: CommutationAnalysis +description: API reference for qiskit.transpiler.passes.CommutationAnalysis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CommutationAnalysis +--- + +# CommutationAnalysis + + + +`qiskit.transpiler.passes.CommutationAnalysis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/commutation_analysis.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Analysis pass to find commutation relations between DAG nodes. + +`property_set['commutation_set']` is a dictionary that describes the commutation relations on a given wire, all the gates on a wire are grouped into a set of gates that commute. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CommutationAnalysis pass on dag. + +Run the pass on the DAG, and write the discovered commutation relations into the `property_set`. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeCancellation.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeCancellation.md new file mode 100644 index 00000000000..c1fec588a1e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeCancellation.md @@ -0,0 +1,130 @@ +--- +title: CommutativeCancellation +description: API reference for qiskit.transpiler.passes.CommutativeCancellation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CommutativeCancellation +--- + +# CommutativeCancellation + + + +`qiskit.transpiler.passes.CommutativeCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/commutative_cancellation.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Cancel the redundant (self-adjoint) gates through commutation relations. + +Pass for cancelling self-inverse gates/rotations. The cancellation utilizes the commutation relations in the circuit. Gates considered include: + +```python +H, X, Y, Z, CX, CY, CZ +``` + +CommutativeCancellation initializer. + +**Parameters** + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Basis gates to consider, e.g. `['u3', 'cx']`. For the effects of this pass, the basis is the set intersection between the `basis_gates` parameter and the gates in the dag. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `basis_gates` and `target` are specified then this argument will take precedence and `basis_gates` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CommutativeCancellation pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – when the 1-qubit rotation gates are not found + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeInverseCancellation.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeInverseCancellation.md new file mode 100644 index 00000000000..5531da9815b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CommutativeInverseCancellation.md @@ -0,0 +1,113 @@ +--- +title: CommutativeInverseCancellation +description: API reference for qiskit.transpiler.passes.CommutativeInverseCancellation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CommutativeInverseCancellation +--- + +# CommutativeInverseCancellation + + + +`qiskit.transpiler.passes.CommutativeInverseCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/commutative_inverse_cancellation.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Cancel pairs of inverse gates exploiting commutation relations. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CommutativeInverseCancellation pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – the directed acyclic graph to run on. + +**Returns** + +Transformed DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Commuting2qGateRouter.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Commuting2qGateRouter.md new file mode 100644 index 00000000000..f8ae6d582e5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Commuting2qGateRouter.md @@ -0,0 +1,206 @@ +--- +title: Commuting2qGateRouter +description: API reference for qiskit.transpiler.passes.Commuting2qGateRouter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Commuting2qGateRouter +--- + +# Commuting2qGateRouter + + + +`qiskit.transpiler.passes.Commuting2qGateRouter(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/routing/commuting_2q_gate_routing/commuting_2q_gate_router.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +A class to swap route one or more commuting gates to the coupling map. + +This pass routes blocks of commuting two-qubit gates encapsulated as `Commuting2qBlock` instructions. This pass will not apply to other instructions. The mapping to the coupling map is done using swap strategies, see `SwapStrategy`. The swap strategy should suit the problem and the coupling map. This transpiler pass should ideally be executed before the quantum circuit is enlarged with any idle ancilla qubits. Otherwise, we may swap qubits outside the portion of the chip we want to use. Therefore, the swap strategy and its associated coupling map do not represent physical qubits. Instead, they represent an intermediate mapping that corresponds to the physical qubits once the initial layout is applied. The example below shows how to map a four qubit [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate") to qubits 0, 1, 3, and 4 of the five qubit device with the coupling map + +```python +0 -- 1 -- 2 + | + 3 + | + 4 +``` + +To do this we use a line swap strategy for qubits 0, 1, 3, and 4 defined it in terms of virtual qubits 0, 1, 2, and 3. + +```python +from qiskit import QuantumCircuit +from qiskit.opflow import PauliSumOp +from qiskit.circuit.library import PauliEvolutionGate +from qiskit.transpiler import Layout, CouplingMap, PassManager +from qiskit.transpiler.passes import FullAncillaAllocation +from qiskit.transpiler.passes import EnlargeWithAncilla +from qiskit.transpiler.passes import ApplyLayout +from qiskit.transpiler.passes import SetLayout + +from qiskit.transpiler.passes.routing.commuting_2q_gate_routing import ( + SwapStrategy, + FindCommutingPauliEvolutions, + Commuting2qGateRouter, +) + +# Define the circuit on virtual qubits +op = PauliSumOp.from_list([("IZZI", 1), ("ZIIZ", 2), ("ZIZI", 3)]) +circ = QuantumCircuit(4) +circ.append(PauliEvolutionGate(op, 1), range(4)) + +# Define the swap strategy on qubits before the initial_layout is applied. +swap_strat = SwapStrategy.from_line([0, 1, 2, 3]) + +# Chose qubits 0, 1, 3, and 4 from the backend coupling map shown above. +backend_cmap = CouplingMap(couplinglist=[(0, 1), (1, 2), (1, 3), (3, 4)]) +initial_layout = Layout.from_intlist([0, 1, 3, 4], *circ.qregs) + +pm_pre = PassManager( + [ + FindCommutingPauliEvolutions(), + Commuting2qGateRouter(swap_strat), + SetLayout(initial_layout), + FullAncillaAllocation(backend_cmap), + EnlargeWithAncilla(), + ApplyLayout(), + ] +) + +# Insert swap gates, map to initial_layout and finally enlarge with ancilla. +pm_pre.run(circ).draw("mpl") +``` + +This pass manager relies on the `current_layout` which corresponds to the qubit layout as swap gates are applied. The pass will traverse all nodes in the dag. If a node should be routed using a swap strategy then it will be decomposed into sub-instructions with swap layers in between and the `current_layout` will be modified. Nodes that should not be routed using swap strategies will be added back to the dag taking the `current_layout` into account. + +**Parameters** + +* **swap\_strategy** – An instance of a `SwapStrategy` that holds the swap layers that are used, and the order in which to apply them, to map the instruction to the hardware. If this field is not given, it should be contained in the property set of the pass. This allows other passes to determine the most appropriate swap strategy at run-time. +* **edge\_coloring** – An optional edge coloring of the coupling map (I.e. no two edges that share a node have the same color). If the edge coloring is given then the commuting gates that can be simultaneously applied given the current qubit permutation are grouped according to the edge coloring and applied according to this edge coloring. Here, a color is an int which is used as the index to define and access the groups of commuting gates that can be applied simultaneously. If the edge coloring is not given then the sets will be built-up using a greedy algorithm. The edge coloring is useful to position gates such as `RZZGate`s next to swap gates to exploit CX cancellations. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the pass by decomposing the nodes it applies on. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – The dag to which we will add swaps. + +**Returns** + +A dag where swaps have been added for the intended gate type. + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the swap strategy was not given at init time and there is no swap strategy in the property set. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the quantum circuit contains more than one qubit register. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If there are qubits that are not contained in the quantum register. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### swap\_decompose + + + +`swap_decompose(dag, node, current_layout, swap_strategy)` + +Take an instance of `Commuting2qBlock` and map it to the coupling map. + +The mapping is done with the swap strategy. + +**Parameters** + +* **dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – The dag which contains the `Commuting2qBlock` we route. +* **node** ([*DAGOpNode*](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.dagnode.DAGOpNode")) – A node whose operation is a `Commuting2qBlock`. +* **current\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")) – The layout before the swaps are applied. This function will modify the layout so that subsequent gates can be properly composed on the dag. +* **swap\_strategy** (*SwapStrategy*) – The swap strategy used to decompose the node. + +**Returns** + +A dag that is compatible with the coupling map where swap gates have been added to map the gates in the `Commuting2qBlock` to the hardware. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConsolidateBlocks.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConsolidateBlocks.md new file mode 100644 index 00000000000..39886219d29 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConsolidateBlocks.md @@ -0,0 +1,121 @@ +--- +title: ConsolidateBlocks +description: API reference for qiskit.transpiler.passes.ConsolidateBlocks +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ConsolidateBlocks +--- + +# ConsolidateBlocks + + + +`qiskit.transpiler.passes.ConsolidateBlocks(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/consolidate_blocks.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Replace each block of consecutive gates by a single Unitary node. + +Pass to consolidate sequences of uninterrupted gates acting on the same qubits into a Unitary node, to be resynthesized later, to a potentially more optimal subcircuit. + +**Notes** + +This pass assumes that the ‘blocks\_list’ property that it reads is given such that blocks are in topological order. The blocks are collected by a previous pass, such as Collect2qBlocks. + +ConsolidateBlocks initializer. + +If `kak_basis_gate` is not `None` it will be used as the basis gate for KAK decomposition. Otherwise, if `basis_gates` is not `None` a basis gate will be chosen from this list. Otherwise, the basis gate will be [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate"). + +**Parameters** + +* **kak\_basis\_gate** ([*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")) – Basis gate for KAK decomposition. +* **force\_consolidate** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Force block consolidation. +* **basis\_gates** (*List(*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*)*) – Basis gates from which to choose a KAK gate. +* **approximation\_degree** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – a float between $[0.0, 1.0]$. Lower approximates more. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The target object for the compilation target backend. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ConsolidateBlocks pass on dag. + +Iterate over each block and replace it with an equivalent Unitary on the same wires. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConstrainedReschedule.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConstrainedReschedule.md new file mode 100644 index 00000000000..5e6a0cf3181 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConstrainedReschedule.md @@ -0,0 +1,175 @@ +--- +title: ConstrainedReschedule +description: API reference for qiskit.transpiler.passes.ConstrainedReschedule +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ConstrainedReschedule +--- + +# ConstrainedReschedule + + + +`qiskit.transpiler.passes.ConstrainedReschedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/alignments/reschedule.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Rescheduler pass that updates node start times to conform to the hardware alignments. + +This pass shifts DAG node start times previously scheduled with one of the scheduling passes, e.g. [`ASAPScheduleAnalysis`](qiskit.transpiler.passes.ASAPScheduleAnalysis "qiskit.transpiler.passes.ASAPScheduleAnalysis") or [`ALAPScheduleAnalysis`](qiskit.transpiler.passes.ALAPScheduleAnalysis "qiskit.transpiler.passes.ALAPScheduleAnalysis"), so that every instruction start time satisfies alignment constraints. + +**Examples** + +We assume executing the following circuit on a backend with 16 dt of acquire alignment. + +```python + ┌───┐┌────────────────┐┌─┐ +q_0: ┤ X ├┤ Delay(100[dt]) ├┤M├ + └───┘└────────────────┘└╥┘ +c: 1/════════════════════════╩═ + 0 +``` + +Note that delay of 100 dt induces a misalignment of 4 dt at the measurement. This pass appends an extra 12 dt time shift to the input circuit. + +```python + ┌───┐┌────────────────┐┌─┐ +q_0: ┤ X ├┤ Delay(112[dt]) ├┤M├ + └───┘└────────────────┘└╥┘ +c: 1/════════════════════════╩═ + 0 +``` + +**Notes** + +Your backend may execute circuits violating these alignment constraints. However, you may obtain erroneous measurement result because of the untracked phase originating in the instruction misalignment. + +Create new rescheduler pass. + +The alignment values depend on the control electronics of your quantum processor. + +**Parameters** + +* **acquire\_alignment** – Integer number representing the minimum time resolution to trigger acquisition instruction in units of `dt`. +* **pulse\_alignment** – Integer number representing the minimum time resolution to trigger gate instruction in units of `dt`. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run rescheduler. + +This pass should perform rescheduling to satisfy: + +> * All DAGOpNode nodes (except for compiler directives) are placed at start time satisfying hardware alignment constraints. +> * The end time of a node does not overlap with the start time of successor nodes. + +Assumptions: + +> * Topological order and absolute time order of DAGOpNode are consistent. +> * All bits in either qargs or cargs associated with node synchronously start. +> * Start time of qargs and cargs may different due to I/O latency. + +Based on the configurations above, the rescheduler pass takes the following strategy: + +1. **The nodes are processed in the topological order, from the beginning of** + + the circuit (i.e. from left to right). For every node (including compiler directives), the function `_push_node_back` performs steps 2 and 3. + +2. **If the start time of the node violates the alignment constraint,** + + the start time is increased to satisfy the constraint. + +3. **Each immediate successor whose start\_time overlaps the node’s end\_time is** + + pushed backwards (towards the end of the wire). Note that at this point the shifted successor does not need to satisfy the constraints, but this will be taken care of when that successor node itself is processed. + +4. **After every node is processed, all misalignment constraints will be resolved,** + + and there will be no overlap between the nodes. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG circuit to be rescheduled with constraints. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If circuit is not scheduled. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ContainsInstruction.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ContainsInstruction.md new file mode 100644 index 00000000000..c5a830ac52b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ContainsInstruction.md @@ -0,0 +1,110 @@ +--- +title: ContainsInstruction +description: API reference for qiskit.transpiler.passes.ContainsInstruction +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ContainsInstruction +--- + +# ContainsInstruction + + + +`qiskit.transpiler.passes.ContainsInstruction(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/contains_instruction.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +An analysis pass to detect if the DAG contains a specific instruction. + +This pass takes in a single instruction name for example `'delay'` and will set the property set `contains_delay` to `True` if the DAG contains that instruction and `False` if it does not. + +ContainsInstruction initializer. + +**Parameters** + +* **instruction\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| Iterable\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – The instruction or instructions to check are in the DAG. The output in the property set is set to `contains_` prefixed on each value for this parameter. +* **recurse** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if `True` (default), then recurse into control-flow operations. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the ContainsInstruction pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConvertConditionsToIfOps.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConvertConditionsToIfOps.md new file mode 100644 index 00000000000..4ba3d869898 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ConvertConditionsToIfOps.md @@ -0,0 +1,111 @@ +--- +title: ConvertConditionsToIfOps +description: API reference for qiskit.transpiler.passes.ConvertConditionsToIfOps +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ConvertConditionsToIfOps +--- + +# ConvertConditionsToIfOps + + + +`qiskit.transpiler.passes.ConvertConditionsToIfOps(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/convert_conditions_to_if_ops.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Convert instructions whose `condition` attribute is set to a non-`None` value into the equivalent single-statement `IfElseBlock`. + +This is a simple pass aimed at easing the conversion from the old style of using [`InstructionSet.c_if()`](qiskit.circuit.InstructionSet#c_if "qiskit.circuit.InstructionSet.c_if") into the new style of using more complex conditional logic. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run a pass on the DAGCircuit. This is implemented by the pass developer. + +**Parameters** + +**dag** – the dag on which the pass is run. + +**Raises** + +[**NotImplementedError**](https://docs.python.org/3/library/exceptions.html#NotImplementedError "(in Python v3.12)") – when this is left unimplemented for a pass. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOps.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOps.md new file mode 100644 index 00000000000..54e27a4304a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOps.md @@ -0,0 +1,103 @@ +--- +title: CountOps +description: API reference for qiskit.transpiler.passes.CountOps +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CountOps +--- + +# CountOps + + + +`qiskit.transpiler.passes.CountOps(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/count_ops.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Count the operations in a DAG circuit. + +The result is saved in `property_set['count_ops']` as an integer. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CountOps pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOpsLongestPath.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOpsLongestPath.md new file mode 100644 index 00000000000..b304a4a53bb --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CountOpsLongestPath.md @@ -0,0 +1,103 @@ +--- +title: CountOpsLongestPath +description: API reference for qiskit.transpiler.passes.CountOpsLongestPath +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CountOpsLongestPath +--- + +# CountOpsLongestPath + + + +`qiskit.transpiler.passes.CountOpsLongestPath(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/count_ops_longest_path.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Count the operations on the longest path in a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit"). + +The result is saved in `property_set['count_ops_longest_path']` as an integer. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the CountOpsLongestPath pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.CrosstalkAdaptiveSchedule.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CrosstalkAdaptiveSchedule.md new file mode 100644 index 00000000000..cfa0a9505d4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.CrosstalkAdaptiveSchedule.md @@ -0,0 +1,343 @@ +--- +title: CrosstalkAdaptiveSchedule +description: API reference for qiskit.transpiler.passes.CrosstalkAdaptiveSchedule +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.CrosstalkAdaptiveSchedule +--- + +# CrosstalkAdaptiveSchedule + + + +`qiskit.transpiler.passes.CrosstalkAdaptiveSchedule(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/crosstalk_adaptive_schedule.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Crosstalk mitigation through adaptive instruction scheduling. + +CrosstalkAdaptiveSchedule initializer. + + + The class `qiskit.transpiler.passes.optimization.crosstalk_adaptive_schedule.CrosstalkAdaptiveSchedule` is deprecated as of qiskit 0.46. It will be removed in the 1.0.0 release. + + +**Parameters** + +* **backend\_prop** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – backend properties object + +* **crosstalk\_prop** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – + + crosstalk properties object crosstalk\_prop\[g1]\[g2] specifies the conditional error rate of g1 when g1 and g2 are executed simultaneously. g1 should be a two-qubit tuple of the form (x,y) where x and y are physical qubit ids. g2 can be either two-qubit tuple (x,y) or single-qubit tuple (x). We currently ignore crosstalk between pairs of single-qubit gates. Gate pairs which are not specified are assumed to be crosstalk free. + + Example: + + ```python + crosstalk_prop = {(0, 1) : {(2, 3) : 0.2, (2) : 0.15}, + (4, 5) : {(2, 3) : 0.1}, + (2, 3) : {(0, 1) : 0.05, (4, 5): 0.05}} + ``` + + The keys of the crosstalk\_prop are tuples for ordered tuples for CX gates e.g., (0, 1) corresponding to CX 0, 1 in the hardware. Each key has an associated value dict which specifies the conditional error rates with nearby gates e.g., `(0, 1) : {(2, 3) : 0.2, (2) : 0.15}` means that CNOT 0, 1 has an error rate of 0.2 when it is executed in parallel with CNOT 2,3 and an error rate of 0.15 when it is executed in parallel with a single qubit gate on qubit 2. + +* **weight\_factor** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – weight of gate error/crosstalk terms in the objective $weight_factor*fidelities + (1-weight_factor)*decoherence errors$. Weight can be varied from 0 to 1, with 0 meaning that only decoherence errors are optimized and 1 meaning that only crosstalk errors are optimized. weight\_factor should be tuned per application to get the best results. + +* **measured\_qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list of qubits that will be measured in a particular circuit. This arg need not be specified for circuits which already include measure gates. The arg is useful when a subsequent module such as state\_tomography\_circuits inserts the measure gates. If CrosstalkAdaptiveSchedule is made aware of those measurements, it is included in the optimization. + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – A target representing the target backend, if both `backend_prop` and `target` are specified then this argument will take precedence and `coupling_map` will be ignored. + +**Raises** + +[**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.12)") – if unable to import z3 solver + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### assign\_gate\_id + + + +`assign_gate_id(dag)` + +ID for each gate + +### basic\_bounds + + + +`basic_bounds()` + +Basic variable bounds for optimization + +### check\_dag\_dependency + + + +`check_dag_dependency(gate1, gate2)` + +gate2 is a DAG dependent of gate1 if it is a descendant of gate1 + +### check\_xtalk\_dependency + + + +`check_xtalk_dependency(t_1, t_2)` + +Check if two gates have a crosstalk dependency. We do not consider crosstalk between pairs of single qubit gates. + +### coherence\_constraints + + + +`coherence_constraints()` + +Set decoherence errors based on qubit lifetimes + +### create\_updated\_dag + + + +`create_updated_dag(layers, barriers)` + +Given a set of layers and barriers, construct a new dag + +### create\_z3\_vars + + + +`create_z3_vars()` + +Setup the variables required for Z3 optimization + +### cx\_tuple + + + +`cx_tuple(gate)` + +Representation for two-qubit gate Note: current implementation assumes that the CX error rates and crosstalk behavior are independent of gate direction + +### enforce\_schedule\_on\_dag + + + +`enforce_schedule_on_dag(input_gate_times)` + +Z3 outputs start times for each gate. Some gates need to be serialized to implement the Z3 schedule. This function inserts barriers to implement those serializations + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### extract\_crosstalk\_relevant\_sets + + + +`extract_crosstalk_relevant_sets()` + +Extract the set of program gates which potentially have crosstalk noise + +### extract\_dag\_overlap\_sets + + + +`extract_dag_overlap_sets(dag)` + +Gate A, B are overlapping if A is neither a descendant nor an ancestor of B. Currently overlaps (A,B) are considered when A is a 2q gate and B is either 2q or 1q gate. + +### extract\_solution + + + +`extract_solution()` + +Extract gate start and finish times from Z3 solution + +### fidelity\_constraints + + + +`fidelity_constraints()` + +Set gate fidelity based on gate overlap conditions + +### filter\_candidates + + + +`filter_candidates(candidates, layer, layer_id, triplet)` + +For a gate G and layer L, L is a candidate layer for G if no gate in L has a DAG dependency with G, and if Z3 allows gates in L and G to overlap. + +### find\_layer + + + +`find_layer(layers, triplet)` + +Find the appropriate layer for a gate + +### gate\_tuple + + + +`gate_tuple(gate)` + +Representation for gate + +### generate\_barriers + + + +`generate_barriers(layers)` + +For each gate g, see if a barrier is required to serialize it with some previously processed gate + +### is\_significant\_xtalk + + + +`is_significant_xtalk(gate1, gate2)` + +Given two conditional gate error rates check if there is high crosstalk by comparing with independent error rates. + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### objective\_function + + + +`objective_function()` + +Objective function is a weighted combination of gate errors and decoherence errors + +### parse\_backend\_properties + + + +`parse_backend_properties()` + +This function assumes that gate durations and coherence times are in seconds in backend.properties() This function converts gate durations and coherence times to nanoseconds. + +### powerset + + + +`powerset(iterable)` + +Finds the set of all subsets of the given iterable This function is used to generate constraints for the Z3 optimization + +### r2f + + + +`r2f(val)` + +Convert Z3 Real to Python float + +### reset + + + +`reset()` + +Reset variables + +### run + + + +`run(dag)` + +Main scheduling function + +### scheduling\_constraints + + + +`scheduling_constraints()` + +DAG scheduling constraints optimization Sets overlap indicator variables + +### singleq\_tuple + + + +`singleq_tuple(gate)` + +Representation for single-qubit gate + +### solve\_optimization + + + +`solve_optimization()` + +Setup and solve a Z3 optimization for finding the best schedule + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGFixedPoint.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGFixedPoint.md new file mode 100644 index 00000000000..12c18cf9320 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGFixedPoint.md @@ -0,0 +1,103 @@ +--- +title: DAGFixedPoint +description: API reference for qiskit.transpiler.passes.DAGFixedPoint +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.DAGFixedPoint +--- + +# DAGFixedPoint + + + +`qiskit.transpiler.passes.DAGFixedPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/dag_fixed_point.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Check if the DAG has reached a fixed point. + +A dummy analysis pass that checks if the DAG a fixed point (the DAG is not modified anymore). The result is saved in `property_set['dag_fixed_point']` as a boolean. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the DAGFixedPoint pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGLongestPath.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGLongestPath.md new file mode 100644 index 00000000000..1328258ffe0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DAGLongestPath.md @@ -0,0 +1,101 @@ +--- +title: DAGLongestPath +description: API reference for qiskit.transpiler.passes.DAGLongestPath +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.DAGLongestPath +--- + +# DAGLongestPath + + + +`qiskit.transpiler.passes.DAGLongestPath(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/dag_longest_path.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Return the longest path in a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") as a list of [`DAGOpNode`](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")s, [`DAGInNode`](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")s, and [`DAGOutNode`](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")s. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the DAGLongestPath pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Decompose.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Decompose.md new file mode 100644 index 00000000000..30426cc1e85 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Decompose.md @@ -0,0 +1,119 @@ +--- +title: Decompose +description: API reference for qiskit.transpiler.passes.Decompose +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Decompose +--- + +# Decompose + + + +`qiskit.transpiler.passes.Decompose(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/basis/decompose.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Expand a gate in a circuit using its decomposition rules. + +Decompose initializer. + +**Parameters** + +**gates\_to\_decompose** – optional subset of gates to be decomposed, identified by gate label, name or type. Defaults to all gates. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Decompose pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – input dag. + +**Returns** + +output dag where `gate` was expanded. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.DenseLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DenseLayout.md new file mode 100644 index 00000000000..14e6b58238f --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DenseLayout.md @@ -0,0 +1,125 @@ +--- +title: DenseLayout +description: API reference for qiskit.transpiler.passes.DenseLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.DenseLayout +--- + +# DenseLayout + + + +`qiskit.transpiler.passes.DenseLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/dense_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Choose a Layout by finding the most connected subset of qubits. + +This pass associates a physical qubit (int) to each virtual qubit of the circuit (Qubit). + + + Even though a `'layout'` is not strictly a property of the DAG, in the transpiler architecture it is best passed around between passes by being set in `property_set`. + + +DenseLayout initializer. + +**Parameters** + +* **coupling\_map** (*Coupling*) – directed graph representing a coupling map. +* **backend\_prop** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – backend properties object +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – A target representing the target backend. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the DenseLayout pass on dag. + +Pick a convenient layout depending on the best matching qubit connectivity, and set the property layout. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to find layout for. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if dag wider than self.coupling\_map + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Depth.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Depth.md new file mode 100644 index 00000000000..70fd1d5d825 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Depth.md @@ -0,0 +1,105 @@ +--- +title: Depth +description: API reference for qiskit.transpiler.passes.Depth +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Depth +--- + +# Depth + + + +`qiskit.transpiler.passes.Depth(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/depth.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Calculate the depth of a DAG circuit. + +**Parameters** + +**recurse** – whether to allow recursion into control flow. If this is `False` (default), the pass will throw an error when control flow is present, to avoid returning a number with little meaning. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Depth pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.DynamicalDecoupling.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DynamicalDecoupling.md new file mode 100644 index 00000000000..2b3be281520 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.DynamicalDecoupling.md @@ -0,0 +1,202 @@ +--- +title: DynamicalDecoupling +description: API reference for qiskit.transpiler.passes.DynamicalDecoupling +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.DynamicalDecoupling +--- + +# DynamicalDecoupling + + + +`qiskit.transpiler.passes.DynamicalDecoupling(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/dynamical_decoupling.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Dynamical decoupling insertion pass. + +This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. + +As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. + +This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). + +```python +import numpy as np +from qiskit.circuit import QuantumCircuit +from qiskit.circuit.library import XGate +from qiskit.transpiler import PassManager, InstructionDurations +from qiskit.transpiler.passes import ALAPSchedule, DynamicalDecoupling +from qiskit.visualization import timeline_drawer + +# Because the legacy passes do not propagate the scheduling information correctly, it is +# necessary to run a no-op "re-schedule" before the output circuits can be drawn. +def draw(circuit): + from qiskit import transpile + + scheduled = transpile( + circuit, + optimization_level=0, + instruction_durations=InstructionDurations(), + scheduling_method="alap", + ) + return timeline_drawer(scheduled) + +circ = QuantumCircuit(4) +circ.h(0) +circ.cx(0, 1) +circ.cx(1, 2) +circ.cx(2, 3) +circ.measure_all() +durations = InstructionDurations( + [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), + ("cx", [1, 2], 200), ("cx", [2, 3], 300), + ("x", None, 50), ("measure", None, 1000)] +) +# balanced X-X sequence on all qubits +dd_sequence = [XGate(), XGate()] +pm = PassManager([ALAPSchedule(durations), + DynamicalDecoupling(durations, dd_sequence)]) +circ_dd = pm.run(circ) +draw(circ_dd) + +# Uhrig sequence on qubit 0 +n = 8 +dd_sequence = [XGate()] * n +def uhrig_pulse_location(k): + return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 +spacing = [] +for k in range(n): + spacing.append(uhrig_pulse_location(k) - sum(spacing)) +spacing.append(1 - sum(spacing)) +pm = PassManager( + [ + ALAPSchedule(durations), + DynamicalDecoupling(durations, dd_sequence, qubits=[0], spacing=spacing), + ] +) +circ_dd = pm.run(circ) +draw(circ_dd) +``` + +![../\_images/qiskit-transpiler-passes-DynamicalDecoupling-1\_00.png](/images/api/qiskit/0.46/qiskit-transpiler-passes-DynamicalDecoupling-1_00.png) + +![../\_images/qiskit-transpiler-passes-DynamicalDecoupling-1\_01.png](/images/api/qiskit/0.46/qiskit-transpiler-passes-DynamicalDecoupling-1_01.png) + +Dynamical decoupling initializer. + + + The class `qiskit.transpiler.passes.scheduling.dynamical_decoupling.DynamicalDecoupling` is pending deprecation as of qiskit 0.21.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use [`PadDynamicalDecoupling`](qiskit.transpiler.passes.PadDynamicalDecoupling "qiskit.transpiler.passes.PadDynamicalDecoupling"), which performs the same function but requires scheduling and alignment analysis passes to run prior to it. + + +**Parameters** + +* **durations** ([*InstructionDurations*](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations")) – Durations of instructions to be used in scheduling. +* **dd\_sequence** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")*]*) – sequence of gates to apply in idle spots. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). +* **spacing** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – a list of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. +* **skip\_reset\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptile to decoherence). +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `durations` and this are specified then this argument will take precedence and `durations` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the DynamicalDecoupling pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – a scheduled DAG. + +**Returns** + +**equivalent circuit with delays interrupted by DD,** + +where possible. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the circuit is not mapped on physical qubits. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md new file mode 100644 index 00000000000..c6b75b9e147 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.EchoRZXWeylDecomposition.md @@ -0,0 +1,128 @@ +--- +title: EchoRZXWeylDecomposition +description: API reference for qiskit.transpiler.passes.EchoRZXWeylDecomposition +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.EchoRZXWeylDecomposition +--- + +# EchoRZXWeylDecomposition + + + +`qiskit.transpiler.passes.EchoRZXWeylDecomposition(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/echo_rzx_weyl_decomposition.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Rewrite two-qubit gates using the Weyl decomposition. + +This transpiler pass rewrites two-qubit gates in terms of echoed cross-resonance gates according to the Weyl decomposition. A two-qubit gate will be replaced with at most six non-echoed RZXGates. Each pair of RZXGates forms an echoed RZXGate. + +EchoRZXWeylDecomposition pass. + +**Parameters** + +* **instruction\_schedule\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")) – the mapping from circuit [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") names and arguments to [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule")s. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `instruction_schedule_map` and `target` are specified then this argument will take precedence and `instruction_schedule_map` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the EchoRZXWeylDecomposition pass on dag. + +Rewrites two-qubit gates in an arbitrary circuit in terms of echoed cross-resonance gates by computing the Weyl decomposition of the corresponding unitary. Modifies the input dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to rewrite. + +**Returns** + +The modified dag. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the circuit cannot be rewritten. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.EnlargeWithAncilla.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.EnlargeWithAncilla.md new file mode 100644 index 00000000000..45ee5cfc614 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.EnlargeWithAncilla.md @@ -0,0 +1,119 @@ +--- +title: EnlargeWithAncilla +description: API reference for qiskit.transpiler.passes.EnlargeWithAncilla +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.EnlargeWithAncilla +--- + +# EnlargeWithAncilla + + + +`qiskit.transpiler.passes.EnlargeWithAncilla(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/enlarge_with_ancilla.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Extend the dag with virtual qubits that are in layout but not in the circuit yet. + +Extend the DAG circuit with new virtual qubits (ancilla) that are specified in the layout, but not present in the circuit. Which qubits to add are previously allocated in the `layout` property, by a previous pass. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the EnlargeWithAncilla pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to extend. + +**Returns** + +An extended DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If there is no layout in the property set or not set at init time. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.FixedPoint.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.FixedPoint.md new file mode 100644 index 00000000000..782f1854b39 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.FixedPoint.md @@ -0,0 +1,109 @@ +--- +title: FixedPoint +description: API reference for qiskit.transpiler.passes.FixedPoint +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.FixedPoint +--- + +# FixedPoint + + + +`qiskit.transpiler.passes.FixedPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/fixed_point.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Check if a property reached a fixed point. + +A dummy analysis pass that checks if a property reached a fixed point. The result is saved in `property_set['_fixed_point']` as a boolean. + +FixedPoint initializer. + +**Parameters** + +**property\_to\_check** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The property to check if a fixed point was reached. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the FixedPoint pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.FullAncillaAllocation.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.FullAncillaAllocation.md new file mode 100644 index 00000000000..03ad511ef7a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.FullAncillaAllocation.md @@ -0,0 +1,141 @@ +--- +title: FullAncillaAllocation +description: API reference for qiskit.transpiler.passes.FullAncillaAllocation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.FullAncillaAllocation +--- + +# FullAncillaAllocation + + + +`qiskit.transpiler.passes.FullAncillaAllocation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/full_ancilla_allocation.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Allocate all idle nodes from the coupling map or target as ancilla on the layout. + +A pass for allocating all idle physical qubits (those that exist in coupling map or target but not the dag circuit) as ancilla. It will also choose new virtual qubits to correspond to those physical ancilla. + + + This is an analysis pass, and only responsible for choosing physical ancilla locations and their corresponding virtual qubits. A separate transformation pass must add those virtual qubits to the circuit. + + +FullAncillaAllocation initializer. + +**Parameters** + +**coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – directed graph representing a coupling map. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the FullAncillaAllocation pass on dag. + +Extend the layout with new (physical qubit, virtual qubit) pairs. The dag signals which virtual qubits are already in the circuit. This pass will allocate new virtual qubits such that no collision occurs (i.e. Layout bijectivity is preserved) + +The coupling\_map and layout together determine which physical qubits are free. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – circuit to analyze + +**Returns** + +returns the same dag circuit, unmodified + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If there is not layout in the property set or not set at init time. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + +### validate\_layout + + + +`static validate_layout(layout_qubits, dag_qubits)` + +Checks if all the qregs in `layout_qregs` already exist in `dag_qregs`. Otherwise, raise. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.GateDirection.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.GateDirection.md new file mode 100644 index 00000000000..429eb001421 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.GateDirection.md @@ -0,0 +1,153 @@ +--- +title: GateDirection +description: API reference for qiskit.transpiler.passes.GateDirection +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.GateDirection +--- + +# GateDirection + + + +`qiskit.transpiler.passes.GateDirection(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/gate_direction.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Modify asymmetric gates to match the hardware coupling direction. + +This pass makes use of the following identities: + +```python + ┌───┐┌───┐┌───┐ +q_0: ──■── q_0: ┤ H ├┤ X ├┤ H ├ + ┌─┴─┐ = ├───┤└─┬─┘├───┤ +q_1: ┤ X ├ q_1: ┤ H ├──■──┤ H ├ + └───┘ └───┘ └───┘ + + + global phase: 3π/2 + ┌──────┐ ┌───┐ ┌────┐┌─────┐┌──────┐┌───┐ +q_0: ┤0 ├ q_0: ─┤ S ├─┤ √X ├┤ Sdg ├┤1 ├┤ H ├ + │ ECR │ = ┌┴───┴┐├────┤└┬───┬┘│ Ecr │├───┤ +q_1: ┤1 ├ q_1: ┤ Sdg ├┤ √X ├─┤ S ├─┤0 ├┤ H ├ + └──────┘ └─────┘└────┘ └───┘ └──────┘└───┘ + + + ┌──────┐ ┌───┐┌──────┐┌───┐ +q_0: ┤0 ├ q_0: ┤ H ├┤1 ├┤ H ├ + │ RZX │ = ├───┤│ RZX │├───┤ +q_1: ┤1 ├ q_1: ┤ H ├┤0 ├┤ H ├ + └──────┘ └───┘└──────┘└───┘ +``` + +This pass assumes that the positions of the qubits in the `DAGCircuit.qubits` attribute are the physical qubit indicies. For example if `dag.qubits[0]` is qubit 0 in the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") or [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"). + +GateDirection pass. + +**Parameters** + +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Directed graph represented a coupling map. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The backend target to use for this pass. If this is specified it will be used instead of the coupling map + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the GateDirection pass on dag. + +Flips the cx nodes to match the directed coupling map. Modifies the input dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to map. + +**Returns** + +The rearranged dag for the coupling map + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the circuit cannot be mapped just by flipping the cx nodes. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.GatesInBasis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.GatesInBasis.md new file mode 100644 index 00000000000..7010627786c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.GatesInBasis.md @@ -0,0 +1,108 @@ +--- +title: GatesInBasis +description: API reference for qiskit.transpiler.passes.GatesInBasis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.GatesInBasis +--- + +# GatesInBasis + + + +`qiskit.transpiler.passes.GatesInBasis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/gates_basis.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Check if all gates in a DAG are in a given set of gates + +Initialize the GatesInBasis pass. + +**Parameters** + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The list of strings representing the set of basis gates. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The target representing the backend. If specified this will be used instead of the `basis_gates` parameter + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the GatesInBasis pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.HighLevelSynthesis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.HighLevelSynthesis.md new file mode 100644 index 00000000000..7fa71572ee4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.HighLevelSynthesis.md @@ -0,0 +1,152 @@ +--- +title: HighLevelSynthesis +description: API reference for qiskit.transpiler.passes.HighLevelSynthesis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.HighLevelSynthesis +--- + +# HighLevelSynthesis + + + +`qiskit.transpiler.passes.HighLevelSynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/high_level_synthesis.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Synthesize higher-level objects and unroll custom definitions. + +The input to this pass is a DAG that may contain higher-level objects, including abstract mathematical objects (e.g., objects of type [`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction")), annotated operations (objects of type [`AnnotatedOperation`](qiskit.circuit.AnnotatedOperation "qiskit.circuit.AnnotatedOperation")), and custom gates. + +In the most common use-case when either `basis_gates` or `target` is specified, all higher-level objects are synthesized, so the output is a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") without such objects. More precisely, every gate in the output DAG is either directly supported by the target, or is in `equivalence_library`. + +The abstract mathematical objects are synthesized using synthesis plugins, applying synthesis methods specified in the high-level-synthesis config (refer to the documentation for `HLSConfig`). + +As an example, let us assume that `op_a` and `op_b` are names of two higher-level objects, that `op_a`-objects have two synthesis methods `default` which does require any additional parameters and `other` with two optional integer parameters `option_1` and `option_2`, that `op_b`-objects have a single synthesis method `default`, and `qc` is a quantum circuit containing `op_a` and `op_b` objects. The following code snippet: + +```python +hls_config = HLSConfig(op_b=[("other", {"option_1": 7, "option_2": 4})]) +pm = PassManager([HighLevelSynthesis(hls_config=hls_config)]) +transpiled_qc = pm.run(qc) +``` + +shows how to run the alternative synthesis method `other` for `op_b`-objects, while using the `default` methods for all other high-level objects, including `op_a`-objects. + +The annotated operations (consisting of a base operation and a list of inverse, control and power modifiers) are synthesizing recursively, first synthesizing the base operation, and then applying synthesis methods for creating inverted, controlled, or powered versions of that). + +The custom gates are synthesized by recursively unrolling their definitions, until every gate is either supported by the target or is in the equivalence library. + +When neither `basis_gates` nor `target` is specified, the pass synthesizes only the top-level abstract mathematical objects and annotated operations, without descending into the gate `definitions`. This is consistent with the older behavior of the pass, allowing to synthesize some higher-level objects using plugins and leaving the other gates untouched. + +HighLevelSynthesis initializer. + +**Parameters** + +* **hls\_config** – Optional, the high-level-synthesis config that specifies synthesis methods and parameters for various high-level-objects in the circuit. If it is not specified, the default synthesis methods and parameters will be used. +* **coupling\_map** – Optional, directed graph represented as a coupling map. +* **target** – Optional, the backend target to use for this pass. If it is specified, it will be used instead of the coupling map. +* **use\_qubit\_indices** – a flag indicating whether this synthesis pass is running before or after the layout is set, that is, whether the qubit indices of higher-level-objects correspond to qubit indices on the target backend. +* **equivalence\_library** – The equivalence library used (instructions in this library will not be unrolled by this pass). +* **basis\_gates** – Optional, target basis names to unroll to, e.g. \[‘u3’, ‘cx’]. Ignored if `target` is also specified. +* **min\_qubits** – The minimum number of qubits for operations in the input dag to translate. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the HighLevelSynthesis pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – input dag. + +**Returns** + +Output dag with higher-level operations synthesized. + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – when the transpiler is unable to synthesize the given DAG +* **(****for instance****, ****when the specified synthesis method is not available****)\*\*\*\*.** – + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.HoareOptimizer.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.HoareOptimizer.md new file mode 100644 index 00000000000..82995d4f8ac --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.HoareOptimizer.md @@ -0,0 +1,119 @@ +--- +title: HoareOptimizer +description: API reference for qiskit.transpiler.passes.HoareOptimizer +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.HoareOptimizer +--- + +# HoareOptimizer + + + +`qiskit.transpiler.passes.HoareOptimizer(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/hoare_opt.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +This is a transpiler pass using Hoare logic circuit optimization. The inner workings of this are detailed in: [https://arxiv.org/abs/1810.00375](https://arxiv.org/abs/1810.00375) + +**Parameters** + +**size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – size of gate cache, in number of gates + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – if unable to import z3 solver + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the directed acyclic graph to run on. + +**Returns** + +Transformed DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.InstructionDurationCheck.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.InstructionDurationCheck.md new file mode 100644 index 00000000000..3c2e3f6023d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.InstructionDurationCheck.md @@ -0,0 +1,118 @@ +--- +title: InstructionDurationCheck +description: API reference for qiskit.transpiler.passes.InstructionDurationCheck +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.InstructionDurationCheck +--- + +# InstructionDurationCheck + + + +`qiskit.transpiler.passes.InstructionDurationCheck(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/alignments/check_durations.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Duration validation pass for reschedule. + +This pass investigates the input quantum circuit and checks if the circuit requires rescheduling for execution. Note that this pass can be triggered without scheduling. This pass only checks the duration of delay instructions and user defined pulse gates, which report duration values without pre-scheduling. + +This pass assumes backend supported instructions, i.e. basis gates, have no violation of the hardware alignment constraints, which is true in general. + +Create new duration validation pass. + +The alignment values depend on the control electronics of your quantum processor. + +**Parameters** + +* **acquire\_alignment** – Integer number representing the minimum time resolution to trigger acquisition instruction in units of `dt`. +* **pulse\_alignment** – Integer number representing the minimum time resolution to trigger gate instruction in units of `dt`. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run duration validation passes. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG circuit to check instruction durations. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.InverseCancellation.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.InverseCancellation.md new file mode 100644 index 00000000000..d0cbeb09d2d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.InverseCancellation.md @@ -0,0 +1,123 @@ +--- +title: InverseCancellation +description: API reference for qiskit.transpiler.passes.InverseCancellation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.InverseCancellation +--- + +# InverseCancellation + + + +`qiskit.transpiler.passes.InverseCancellation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/inverse_cancellation.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Cancel specific Gates which are inverses of each other when they occur back-to- back. + +Initialize InverseCancellation pass. + +**Parameters** + +**gates\_to\_cancel** – List describing the gates to cancel. Each element of the list is either a single gate or a pair of gates. If a single gate, then it should be self-inverse. If a pair of gates, then the gates in the pair should be inverses of each other. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – Input is not a self-inverse gate or a pair of inverse gates. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the InverseCancellation pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – the directed acyclic graph to run on. + +**Returns** + +Transformed DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Layout2qDistance.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Layout2qDistance.md new file mode 100644 index 00000000000..5880eb4f043 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Layout2qDistance.md @@ -0,0 +1,110 @@ +--- +title: Layout2qDistance +description: API reference for qiskit.transpiler.passes.Layout2qDistance +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Layout2qDistance +--- + +# Layout2qDistance + + + +`qiskit.transpiler.passes.Layout2qDistance(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/layout_2q_distance.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Evaluate how good the layout selection was. + +Saves in `property_set['layout_score']` (or the property name in property\_name) the sum of distances for each circuit CX. The lower the number, the better the selection. Therefore, 0 is a perfect layout selection. No CX direction is considered. + +Layout2qDistance initializer. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – Directed graph represented a coupling map. +* **property\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The property name to save the score. Default: layout\_score + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Layout2qDistance pass on dag. :param dag: DAG to evaluate. :type dag: DAGCircuit + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsSynthesis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsSynthesis.md new file mode 100644 index 00000000000..6d2fe0f55ab --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsSynthesis.md @@ -0,0 +1,124 @@ +--- +title: LinearFunctionsSynthesis +description: API reference for qiskit.transpiler.passes.LinearFunctionsSynthesis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.LinearFunctionsSynthesis +--- + +# LinearFunctionsSynthesis + + + +`qiskit.transpiler.passes.LinearFunctionsSynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/linear_functions_synthesis.py "view source code") + +Bases: [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.synthesis.high_level_synthesis.HighLevelSynthesis") + +DEPRECATED: Synthesize linear functions. + +Under the hood, this runs the default high-level synthesis plugin for linear functions. + + + The class `qiskit.transpiler.passes.synthesis.linear_functions_synthesis.LinearFunctionsSynthesis` is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. Instead, use [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis"). + + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the HighLevelSynthesis pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – input dag. + +**Returns** + +Output dag with higher-level operations synthesized. + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – when the transpiler is unable to synthesize the given DAG +* **(****for instance****, ****when the specified synthesis method is not available****)\*\*\*\*.** – + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsToPermutations.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsToPermutations.md new file mode 100644 index 00000000000..70d12e8ae93 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.LinearFunctionsToPermutations.md @@ -0,0 +1,109 @@ +--- +title: LinearFunctionsToPermutations +description: API reference for qiskit.transpiler.passes.LinearFunctionsToPermutations +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.LinearFunctionsToPermutations +--- + +# LinearFunctionsToPermutations + + + +`qiskit.transpiler.passes.LinearFunctionsToPermutations(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/linear_functions_synthesis.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Promotes linear functions to permutations when possible. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the LinearFunctionsToPermutations pass on dag. :param dag: input dag. + +**Returns** + +Output dag with LinearFunctions synthesized. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.LookaheadSwap.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.LookaheadSwap.md new file mode 100644 index 00000000000..609a0ef0a70 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.LookaheadSwap.md @@ -0,0 +1,145 @@ +--- +title: LookaheadSwap +description: API reference for qiskit.transpiler.passes.LookaheadSwap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.LookaheadSwap +--- + +# LookaheadSwap + + + +`qiskit.transpiler.passes.LookaheadSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/routing/lookahead_swap.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Map input circuit onto a backend topology via insertion of SWAPs. + +Implementation of Sven Jandura’s swap mapper submission for the 2018 Qiskit Developer Challenge, adapted to integrate into the transpiler architecture. + +The role of the swapper pass is to modify the starting circuit to be compatible with the target device’s topology (the set of two-qubit gates available on the hardware.) To do this, the pass will insert SWAP gates to relocate the virtual qubits for each upcoming gate onto a set of coupled physical qubits. However, as SWAP gates are particularly lossy, the goal is to accomplish this remapping while introducing the fewest possible additional SWAPs. + +This algorithm searches through the available combinations of SWAP gates by means of a narrowed best first/beam search, described as follows: + +* Start with a layout of virtual qubits onto physical qubits. +* Find any gates in the input circuit which can be performed with the current layout and mark them as mapped. +* For all possible SWAP gates, calculate the layout that would result from their application and rank them according to the distance of the resulting layout over upcoming gates (see \_calc\_layout\_distance.) +* For the four (search\_width) highest-ranking SWAPs, repeat the above process on the layout that would be generated if they were applied. +* Repeat this process down to a depth of four (search\_depth) SWAPs away from the initial layout, for a total of 256 (search\_width^search\_depth) prospective layouts. +* Choose the layout which maximizes the number of two-qubit which could be performed. Add its mapped gates, including the SWAPs generated, to the output circuit. +* Repeat the above until all gates from the initial circuit are mapped. + +For more details on the algorithm, see Sven’s blog post: [https://medium.com/qiskit/improving-a-quantum-compiler-48410d7a7084](https://medium.com/qiskit/improving-a-quantum-compiler-48410d7a7084) + +LookaheadSwap initializer. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – CouplingMap of the target backend. +* **search\_depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – lookahead tree depth when ranking best SWAP options. +* **search\_width** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – lookahead tree width when ranking best SWAP options. +* **fake\_run** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if true, it will only pretend to do routing, i.e., no swap is effectively added. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the LookaheadSwap pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the directed acyclic graph to be mapped + +**Returns** + +**A dag mapped to be compatible with the coupling\_map in** + +the property\_set. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the coupling map or the layout are not +* **compatible with the DAG**\*\*, or \*\***if the coupling\_map=None** – + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.MergeAdjacentBarriers.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.MergeAdjacentBarriers.md new file mode 100644 index 00000000000..c48fac3fce6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.MergeAdjacentBarriers.md @@ -0,0 +1,138 @@ +--- +title: MergeAdjacentBarriers +description: API reference for qiskit.transpiler.passes.MergeAdjacentBarriers +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.MergeAdjacentBarriers +--- + +# MergeAdjacentBarriers + + + +`qiskit.transpiler.passes.MergeAdjacentBarriers(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/merge_adjacent_barriers.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Return a circuit with any adjacent barriers merged together. + +Only barriers which can be merged without affecting the barrier structure of the DAG will be merged. + +Not all redundant barriers will necessarily be merged, only adjacent barriers are merged. + +For example, the circuit: + +```python +qr = QuantumRegister(3, 'q') +circuit = QuantumCircuit(qr) +circuit.barrier(qr[0]) +circuit.barrier(qr[1]) +circuit.barrier(qr) +``` + +Will be transformed into a circuit corresponding to: + +```python +circuit.barrier(qr[0]) +circuit.barrier(qr) +``` + +i.e, + +```python + ░ ░ ░ ░ +q_0: ─░──░─ q_0: ─░──░─ + ░ ░ ░ ░ +q_1: ─░──░─ => q_1: ────░─ + ░ ░ ░ +q_2: ────░─ q_2: ────░─ + ░ +``` + +after one iteration of the pass. These two barriers were not merged by the first pass as they are not adjacent in the initial circuit. + +The pass then can be reapplied to merge the newly adjacent barriers. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the MergeAdjacentBarriers pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.MinimumPoint.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.MinimumPoint.md new file mode 100644 index 00000000000..d7ca0f3f6fc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.MinimumPoint.md @@ -0,0 +1,121 @@ +--- +title: MinimumPoint +description: API reference for qiskit.transpiler.passes.MinimumPoint +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.MinimumPoint +--- + +# MinimumPoint + + + +`qiskit.transpiler.passes.MinimumPoint(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/minimum_point.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Check if the DAG has reached a relative semi-stable point over previous runs + +This pass is similar to the [`FixedPoint`](qiskit.transpiler.passes.FixedPoint "qiskit.transpiler.passes.FixedPoint") transpiler pass and is intended primarily to be used to set a loop break condition in the property set. However, unlike the [`FixedPoint`](qiskit.transpiler.passes.FixedPoint "qiskit.transpiler.passes.FixedPoint") class which only sets the condition if 2 consecutive runs have the same value property set value this pass is designed to find a local minimum and use that instead. This pass is designed for an optimization loop where a fixed point may never get reached (for example if synthesis is used and there are multiple equivalent outputs for some cases). + +This pass will track the state of fields in the property set over its past executions and set a boolean field when either a fixed point is reached over the backtracking depth or selecting the minimum value found if the backtracking depth is reached. To do this it stores a deep copy of the current minimum DAG in the property set and when `backtrack_depth` number of executions is reached since the last minimum the output dag is set to that copy of the earlier minimum. + +Fields used by this pass in the property set are (all relative to the `prefix` argument): + +* `{prefix}_minimum_point_state` - Used to track the state of the minimum point search + +* **`{prefix}_minimum_point` - This value gets set to `True` when either a fixed point** + + is reached over the `backtrack_depth` executions, or `backtrack_depth` was exceeded and an earlier minimum is restored. + +Initialize an instance of this pass + +**Parameters** + +* **property\_set\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of property set keys that will be used to evaluate the local minimum. The values of these property set keys will be used as a tuple for comparison +* **prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The prefix to use for the property set key that is used for tracking previous evaluations +* **backtrack\_depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of entries to store. If this number is reached and the next iteration doesn’t have a decrease in the number of values the minimum of the previous n will be set as the output dag and `minimum_point` will be set to `True` in the property set + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the MinimumPoint pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.NoiseAdaptiveLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.NoiseAdaptiveLayout.md new file mode 100644 index 00000000000..5fcde96fdca --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.NoiseAdaptiveLayout.md @@ -0,0 +1,156 @@ +--- +title: NoiseAdaptiveLayout +description: API reference for qiskit.transpiler.passes.NoiseAdaptiveLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.NoiseAdaptiveLayout +--- + +# NoiseAdaptiveLayout + + + +`qiskit.transpiler.passes.NoiseAdaptiveLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/noise_adaptive_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Choose a noise-adaptive Layout based on current calibration data for the backend. + +> This pass associates a physical qubit (int) to each virtual qubit of the circuit (Qubit), using calibration data. +> +> The pass implements the qubit mapping method from: Noise-Adaptive Compiler Mappings for Noisy Intermediate-Scale Quantum Computers Prakash Murali, Jonathan M. Baker, Ali Javadi-Abhari, Frederic T. Chong, Margaret R. Martonosi ASPLOS 2019 (arXiv:1901.11054). + +`Ordering of edges` + +`Map qubits edge-by-edge in the order of decreasing frequency of occurrence in the program dag.` + +### Initialization + + + +`Initialization()` + +`If an edge exists with both endpoints unmapped,` + +`pick the best available hardware cx to execute this edge.` + +`Iterative step` + +`When an edge exists with one endpoint unmapped,` + +`map that endpoint to a location which allows` + +`maximum reliability for CNOTs with previously mapped qubits.` + +`In the end if there are unmapped qubits (which don't` + +`participate in any CNOT), map them to any available` + +`hardware qubit.` + +### Notes + + + +`Notes()` + +even though a layout is not strictly a property of the DAG, in the transpiler architecture it is best passed around between passes by being set in property\_set. + +NoiseAdaptiveLayout initializer. + + + The class `qiskit.transpiler.passes.layout.noise_adaptive_layout.NoiseAdaptiveLayout` is deprecated as of qiskit 0.46. It will be removed in the 1.0.0 release. + + +**Parameters** + +* **backend\_prop** (*Union\[*[*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – backend properties object +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Optional. To filter the backend\_prop qubits/gates. This parameter is ignored if [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") is provided in `backend_prop`. That method is preferred. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if invalid options + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the NoiseAdaptiveLayout pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.NormalizeRXAngle.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.NormalizeRXAngle.md new file mode 100644 index 00000000000..e895cfae9d2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.NormalizeRXAngle.md @@ -0,0 +1,156 @@ +--- +title: NormalizeRXAngle +description: API reference for qiskit.transpiler.passes.NormalizeRXAngle +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.NormalizeRXAngle +--- + +# NormalizeRXAngle + + + +`qiskit.transpiler.passes.NormalizeRXAngle(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/normalize_rx_angle.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Normalize theta parameter of RXGate instruction. + +The parameter normalization is performed with following steps. + +1\) Wrap RX Gate theta into \[0, pi]. When theta is negative value, the gate is decomposed into the following sequence. + +```python + ┌───────┐┌─────────┐┌────────┐ +q: ┤ Rz(π) ├┤ Rx(|θ|) ├┤ Rz(-π) ├ + └───────┘└─────────┘└────────┘ +``` + +2. If the operation is supported by target, convert RX(pi/2) to SX, and RX(pi) to X. +3. Quantize theta value according to the user-specified resolution. + +This will help reduce the size of calibration data sent over the wire, and allow us to exploit the more accurate, hardware-calibrated pulses. Note that pulse calibration might be attached per each rotation angle. + +NormalizeRXAngle initializer. + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend. If the target contains SX and X calibrations, this pass will replace the corresponding RX gates with SX and X gates. +* **resolution\_in\_radian** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Resolution for RX rotation angle quantization. If set to zero, this pass won’t modify the rotation angles in the given DAG. (=Provides arbitrary-angle RX) + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### quantize\_angles + + + +`quantize_angles(qubit, original_angle)` + +Quantize the RX rotation angles by assigning the same value for the angles that differ within a resolution provided by the user. + +**Parameters** + +* **qubit** ([*Qubit*](qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – This will be the dict key to access the list of quantized rotation angles. +* **original\_angle** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Original rotation angle, before quantization. + +**Returns** + +Quantized angle. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the NormalizeRXAngle pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – The DAG to be optimized. + +**Returns** + +A DAG with RX gate calibration. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.NumTensorFactors.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.NumTensorFactors.md new file mode 100644 index 00000000000..ea2d6c817a0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.NumTensorFactors.md @@ -0,0 +1,103 @@ +--- +title: NumTensorFactors +description: API reference for qiskit.transpiler.passes.NumTensorFactors +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.NumTensorFactors +--- + +# NumTensorFactors + + + +`qiskit.transpiler.passes.NumTensorFactors(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/num_tensor_factors.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Calculate the number of tensor factors of a DAG circuit. + +The result is saved in `property_set['num_tensor_factors']` as an integer. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the NumTensorFactors pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGates.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGates.md new file mode 100644 index 00000000000..b961c97c5d1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGates.md @@ -0,0 +1,158 @@ +--- +title: Optimize1qGates +description: API reference for qiskit.transpiler.passes.Optimize1qGates +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Optimize1qGates +--- + +# Optimize1qGates + + + +`qiskit.transpiler.passes.Optimize1qGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/optimize_1q_gates.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Optimize chains of single-qubit u1, u2, u3 gates by combining them into a single gate. + +Optimize1qGates initializer. + +**Parameters** + +* **basis** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Basis gates to consider, e.g. \[‘u3’, ‘cx’]. For the effects of this pass, the basis is the set intersection between the basis parameter and the set \{‘u1’,’u2’,’u3’, ‘u’, ‘p’}. +* **eps** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – EPS to check against +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `basis` and `target` are specified then this argument will take precedence and `basis` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### compose\_u3 + + + +`static compose_u3(theta1, phi1, lambda1, theta2, phi2, lambda2)` + +Return a triple theta, phi, lambda for the product. + +**u3(theta, phi, lambda)** + +\= u3(theta1, phi1, lambda1).u3(theta2, phi2, lambda2) = Rz(phi1).Ry(theta1).Rz(lambda1+phi2).Ry(theta2).Rz(lambda2) = Rz(phi1).Rz(phi’).Ry(theta’).Rz(lambda’).Rz(lambda2) = u3(theta’, phi1 + phi’, lambda2 + lambda’) + +Return theta, phi, lambda. + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Optimize1qGates pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if `YZY` and `ZYZ` angles do not give same rotation matrix. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + +### yzy\_to\_zyz + + + +`static yzy_to_zyz(xi, theta1, theta2, eps=1e-09)` + +Express a Y.Z.Y single qubit gate as a Z.Y.Z gate. + +Solve the equation + +$$ +$$ + +Ry(theta1).Rz(xi).Ry(theta2) = Rz(phi).Ry(theta).Rz(lambda) + +for theta, phi, and lambda. + +Return a solution theta, phi, and lambda. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md new file mode 100644 index 00000000000..82534b0eef4 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesDecomposition.md @@ -0,0 +1,129 @@ +--- +title: Optimize1qGatesDecomposition +description: API reference for qiskit.transpiler.passes.Optimize1qGatesDecomposition +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Optimize1qGatesDecomposition +--- + +# Optimize1qGatesDecomposition + + + +`qiskit.transpiler.passes.Optimize1qGatesDecomposition(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/optimize_1q_decomposition.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Optimize chains of single-qubit gates by combining them into a single gate. + +**The decision to replace the original chain with a new re-synthesis depends on:** + +* whether the original chain was out of basis: replace +* whether the original chain was in basis but re-synthesis is lower error: replace +* whether the original chain contains a pulse gate: do not replace +* whether the original chain amounts to identity: replace with null + +Error is computed as a multiplication of the errors of individual gates on that qubit. + +Optimize1qGatesDecomposition initializer. + +**Parameters** + +* **basis** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – Basis gates to consider, e.g. \[‘u3’, ‘cx’]. For the effects of this pass, the basis is the set intersection between the basis parameter and the Euler basis. Ignored if `target` is also specified. +* **target** (*Optional\[*[*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object corresponding to the compilation target. When specified, any argument specified for `basis_gates` is ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Optimize1qGatesDecomposition pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md new file mode 100644 index 00000000000..90dd55fbec6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation.md @@ -0,0 +1,123 @@ +--- +title: Optimize1qGatesSimpleCommutation +description: API reference for qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation +--- + +# Optimize1qGatesSimpleCommutation + + + +`qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/optimize_1q_commutation.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Optimizes 1Q gate strings interrupted by 2Q gates by commuting the components and resynthesizing the results. The commutation rules are stored in `commutation_table`. + +**NOTE: In addition to those mentioned in `commutation_table`, this pass has some limitations:** + +* Does not handle multiple commutations in a row without intermediate progress. +* Can only commute into positions where there are pre-existing runs. +* Does not exhaustively test all the different ways commuting gates can be assigned to either side of a barrier to try to find low-depth configurations. (This is particularly evident if all the gates in a run commute with both the predecessor and the successor barriers.) + +**Parameters** + +* **basis** (*List\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – See also Optimize1qGatesDecomposition. +* **run\_to\_completion** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, this pass retries until it is unable to do any more work. If False, it finds and performs one optimization, and for full optimization the user is obligated to re-call the pass until the output stabilizes. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `basis` and this are specified then this argument will take precedence and `basis` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.OptimizeCliffords.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.OptimizeCliffords.md new file mode 100644 index 00000000000..5adada50bae --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.OptimizeCliffords.md @@ -0,0 +1,113 @@ +--- +title: OptimizeCliffords +description: API reference for qiskit.transpiler.passes.OptimizeCliffords +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.OptimizeCliffords +--- + +# OptimizeCliffords + + + +`qiskit.transpiler.passes.OptimizeCliffords(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/optimize_cliffords.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Combine consecutive Cliffords over the same qubits. This serves as an example of extra capabilities enabled by storing Cliffords natively on the circuit. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the OptimizeCliffords pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDelay.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDelay.md new file mode 100644 index 00000000000..8367f23d71a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDelay.md @@ -0,0 +1,149 @@ +--- +title: PadDelay +description: API reference for qiskit.transpiler.passes.PadDelay +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.PadDelay +--- + +# PadDelay + + + +`qiskit.transpiler.passes.PadDelay(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/padding/pad_delay.py "view source code") + +Bases: `BasePadding` + +Padding idle time with Delay instructions. + +Consecutive delays will be merged in the output of this pass. + +```python +durations = InstructionDurations([("x", None, 160), ("cx", None, 800)]) + +qc = QuantumCircuit(2) +qc.delay(100, 0) +qc.x(1) +qc.cx(0, 1) +``` + +The ASAP-scheduled circuit output may become + +```python + ┌────────────────┐ +q_0: ┤ Delay(160[dt]) ├──■── + └─────┬───┬──────┘┌─┴─┐ +q_1: ──────┤ X ├───────┤ X ├ + └───┘ └───┘ +``` + +Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. + +See `BasePadding` pass for details. + +Create new padding delay pass. + +**Parameters** + +* **fill\_very\_end** – Set `True` to fill the end of circuit with delay. +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend. If it is supplied and does not support delay instruction on a qubit, padding passes do not pad any idle time of the qubit. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the padding pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to be checked. + +**Returns** + +DAG with idle time filled with instructions. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDynamicalDecoupling.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDynamicalDecoupling.md new file mode 100644 index 00000000000..43f549986c8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.PadDynamicalDecoupling.md @@ -0,0 +1,207 @@ +--- +title: PadDynamicalDecoupling +description: API reference for qiskit.transpiler.passes.PadDynamicalDecoupling +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.PadDynamicalDecoupling +--- + +# PadDynamicalDecoupling + + + +`qiskit.transpiler.passes.PadDynamicalDecoupling(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/padding/dynamical_decoupling.py "view source code") + +Bases: `BasePadding` + +Dynamical decoupling insertion pass. + +This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. + +As a special case, the pass allows a length-1 sequence (e.g. `[XGate()]`). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. + +This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). + +```python +import numpy as np +from qiskit.circuit import QuantumCircuit +from qiskit.circuit.library import XGate +from qiskit.transpiler import PassManager, InstructionDurations +from qiskit.transpiler.passes import ALAPScheduleAnalysis, PadDynamicalDecoupling +from qiskit.visualization import timeline_drawer +circ = QuantumCircuit(4) +circ.h(0) +circ.cx(0, 1) +circ.cx(1, 2) +circ.cx(2, 3) +circ.measure_all() +durations = InstructionDurations( + [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), + ("cx", [1, 2], 200), ("cx", [2, 3], 300), + ("x", None, 50), ("measure", None, 1000)] +) + +# balanced X-X sequence on all qubits +dd_sequence = [XGate(), XGate()] +pm = PassManager([ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence)]) +circ_dd = pm.run(circ) +timeline_drawer(circ_dd) + +# Uhrig sequence on qubit 0 +n = 8 +dd_sequence = [XGate()] * n +def uhrig_pulse_location(k): + return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 +spacing = [] +for k in range(n): + spacing.append(uhrig_pulse_location(k) - sum(spacing)) +spacing.append(1 - sum(spacing)) +pm = PassManager( + [ + ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacing=spacing), + ] +) +circ_dd = pm.run(circ) +timeline_drawer(circ_dd) +``` + +![../\_images/qiskit-transpiler-passes-PadDynamicalDecoupling-1\_00.png](/images/api/qiskit/0.46/qiskit-transpiler-passes-PadDynamicalDecoupling-1_00.png) + +![../\_images/qiskit-transpiler-passes-PadDynamicalDecoupling-1\_01.png](/images/api/qiskit/0.46/qiskit-transpiler-passes-PadDynamicalDecoupling-1_01.png) + + + You may need to call alignment pass before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints. + + +Dynamical decoupling initializer. + +**Parameters** + +* **durations** – Durations of instructions to be used in scheduling. + +* **dd\_sequence** – Sequence of gates to apply in idle spots. + +* **qubits** – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). + +* **spacing** – A list of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. + +* **skip\_reset\_qubits** – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptile to decoherence). + +* **pulse\_alignment** – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. + +* **extra\_slack\_distribution** – + + The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. + + > * ”middle”: Put the extra slack to the interval at the middle of the sequence. + > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. + +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `durations` and this are specified then this argument will take precedence and `durations` will be ignored. + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – When invalid DD sequence is specified. +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If `dd_sequence` is not specified + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the padding pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to be checked. + +**Returns** + +DAG with idle time filled with instructions. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.PulseGates.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.PulseGates.md new file mode 100644 index 00000000000..4ca7833a085 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.PulseGates.md @@ -0,0 +1,178 @@ +--- +title: PulseGates +description: API reference for qiskit.transpiler.passes.PulseGates +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.PulseGates +--- + +# PulseGates + + + +`qiskit.transpiler.passes.PulseGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/calibration/pulse_gate.py "view source code") + +Bases: `CalibrationBuilder` + +Pulse gate adding pass. + +This pass adds gate calibrations from the supplied `InstructionScheduleMap` to a quantum circuit. + +This pass checks each DAG circuit node and acquires a corresponding schedule from the instruction schedule map object that may be provided by the target backend. Because this map is a mutable object, the end-user can provide a configured backend to execute the circuit with customized gate implementations. + +This mapping object returns a schedule with “publisher” metadata which is an integer Enum value representing who created the gate schedule. If the gate schedule is provided by end-users, this pass attaches the schedule to the DAG circuit as a calibration. + +This pass allows users to easily override quantum circuit with custom gate definitions without directly dealing with those schedules. + +**References** + +* \[1] OpenQASM 3: A broader and deeper quantum assembly language [https://arxiv.org/abs/2104.14722](https://arxiv.org/abs/2104.14722) + +Create new pass. + +**Parameters** + +* **inst\_map** – Instruction schedule map that user may override. +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `inst_map` and `target` are specified then it updates instructions in the `target` with `inst_map`. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### get\_calibration + + + +`get_calibration(node_op, qubits)` + +Gets the calibrated schedule for the given instruction and qubits. + +**Parameters** + +* **node\_op** ([*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Target instruction object. +* **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")) – Integer qubit indices to check. + +**Returns** + +Return Schedule of target gate instruction. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – When node is parameterized and calibration is raw schedule object. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the calibration adder pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A DAG with calibrations added to it. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### supported + + + +`supported(node_op, qubits)` + +Determine if a given node supports the calibration. + +**Parameters** + +* **node\_op** ([*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Target instruction object. +* **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")) – Integer qubit indices to check. + +**Returns** + +Return `True` is calibration can be provided. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RXCalibrationBuilder.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RXCalibrationBuilder.md new file mode 100644 index 00000000000..6f724095bd2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RXCalibrationBuilder.md @@ -0,0 +1,187 @@ +--- +title: RXCalibrationBuilder +description: API reference for qiskit.transpiler.passes.RXCalibrationBuilder +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RXCalibrationBuilder +--- + +# RXCalibrationBuilder + + + +`qiskit.transpiler.passes.RXCalibrationBuilder(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/calibration/rx_builder.py "view source code") + +Bases: `CalibrationBuilder` + +Add single-pulse RX calibrations that are bootstrapped from the SX calibration. + + + Requirement: NormalizeRXAngles pass (one of the optimization passes). + + +It is recommended to place this pass in the post-optimization stage of a passmanager. A simple demo: + +```python +from qiskit.providers.fake_provider import FakeBelemV2 +from qiskit.transpiler import PassManager, PassManagerConfig +from qiskit.transpiler.preset_passmanagers import level_1_pass_manager +from qiskit.circuit import Parameter +from qiskit.circuit.library import QuantumVolume +from qiskit.circuit.library.standard_gates import RXGate + +from calibration.rx_builder import RXCalibrationBuilder + +qv = QuantumVolume(4, 4, seed=1004) + +# Transpiling with single pulse RX gates enabled +backend_with_single_pulse_rx = FakeBelemV2() +rx_inst_props = {} +for i in range(backend_with_single_pulse_rx.num_qubits): + rx_inst_props[(i,)] = None +backend_with_single_pulse_rx.target.add_instruction(RXGate(Parameter("theta")), rx_inst_props) +config_with_rx = PassManagerConfig.from_backend(backend=backend_with_single_pulse_rx) +pm_with_rx = level_1_pass_manager(pass_manager_config=config_with_rx) +rx_builder = RXCalibrationBuilder(target=backend_with_single_pulse_rx.target) +pm_with_rx.post_optimization = PassManager([rx_builder]) +transpiled_circ_with_single_pulse_rx = pm_with_rx.run(qv) +transpiled_circ_with_single_pulse_rx.count_ops() + +# Conventional transpilation: each RX gate is decomposed into a sequence with two SX gates +original_backend = FakeBelemV2() +original_config = PassManagerConfig.from_backend(backend=original_backend) +original_pm = level_1_pass_manager(pass_manager_config=original_config) +original_transpiled_circ = original_pm.run(qv) +original_transpiled_circ.count_ops() +``` + +**References** + +* \[1]: Gokhale et al. (2020), Optimized Quantum Compilation for Near-Term Algorithms with OpenPulse. arXiv:2004.11205 \<[https://arxiv.org/abs/2004.11205](https://arxiv.org/abs/2004.11205)> + +Bootstrap single-pulse RX gate calibrations from the (hardware-calibrated) SX gate calibration. + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – Should contain a SX calibration that will be +* **calibrations.** (*used for bootstrapping RX*) – + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### get\_calibration + + + +`get_calibration(node_op, qubits)` + +Generate RX calibration for the rotation angle specified in node\_op. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the calibration adder pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A DAG with calibrations added to it. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### supported + + + +`supported(node_op, qubits)` + +Check if the calibration for SX gate exists and it’s a single DRAG pulse. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilder.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilder.md new file mode 100644 index 00000000000..6077af8f5fc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilder.md @@ -0,0 +1,199 @@ +--- +title: RZXCalibrationBuilder +description: API reference for qiskit.transpiler.passes.RZXCalibrationBuilder +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RZXCalibrationBuilder +--- + +# RZXCalibrationBuilder + + + +`qiskit.transpiler.passes.RZXCalibrationBuilder(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/calibration/rzx_builder.py "view source code") + +Bases: `CalibrationBuilder` + +Creates calibrations for RZXGate(theta) by stretching and compressing Gaussian square pulses in the CX gate. This is done by retrieving (for a given pair of qubits) the CX schedule in the instruction schedule map of the backend defaults. The CX schedule must be an echoed cross-resonance gate optionally with rotary tones. The cross-resonance drive tones and rotary pulses must be Gaussian square pulses. The width of the Gaussian square pulse is adjusted so as to match the desired rotation angle. If the rotation angle is small such that the width disappears then the amplitude of the zero width Gaussian square pulse (i.e. a Gaussian) is reduced to reach the target rotation angle. Additional details can be found in [https://arxiv.org/abs/2012.11660](https://arxiv.org/abs/2012.11660). + +Initializes a RZXGate calibration builder. + +**Parameters** + +* **instruction\_schedule\_map** – The `InstructionScheduleMap` object representing the default pulse calibrations for the target backend +* **verbose** – Set True to raise a user warning when RZX schedule cannot be built. +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `instruction_schedule_map` and this are specified then this argument will take precedence and `instruction_schedule_map` will be ignored. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Instruction schedule map is not provided. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### get\_calibration + + + +`get_calibration(node_op, qubits)` + +Builds the calibration schedule for the RZXGate(theta) with echos. + +**Parameters** + +* **node\_op** (*CircuitInst*) – Instruction of the RZXGate(theta). I.e. params\[0] is theta. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of qubits for which to get the schedules. The first qubit is the control and the second is the target. + +**Returns** + +The calibration schedule for the RZXGate(theta). + +**Return type** + +schedule + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if rotation angle is not assigned. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the control and target qubits cannot be identified. +* **CalibrationNotAvailable** – RZX schedule cannot be built for input node. + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### rescale\_cr\_inst + + + +`static rescale_cr_inst(instruction, theta, sample_mult=16)` + +A builder macro to play stretched pulse. + +**Parameters** + +* **instruction** ([*Play*](qiskit.pulse.instructions.Play "qiskit.pulse.instructions.play.Play")) – The instruction from which to create a new shortened or lengthened pulse. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – desired angle, pi/2 is assumed to be the angle that the pulse in the given play instruction implements. +* **sample\_mult** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – All pulses must be a multiple of sample\_mult. + +**Returns** + +Duration of stretched pulse. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if rotation angle is not assigned. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the calibration adder pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A DAG with calibrations added to it. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### supported + + + +`supported(node_op, qubits)` + +Determine if a given node supports the calibration. + +**Parameters** + +* **node\_op** ([*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Target instruction object. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Integer qubit indices to check. + +**Returns** + +Return `True` is calibration can be provided. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md new file mode 100644 index 00000000000..fe8213e1c4e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho.md @@ -0,0 +1,201 @@ +--- +title: RZXCalibrationBuilderNoEcho +description: API reference for qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho +--- + +# RZXCalibrationBuilderNoEcho + + + +`qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/calibration/rzx_builder.py "view source code") + +Bases: [`RZXCalibrationBuilder`](qiskit.transpiler.passes.RZXCalibrationBuilder "qiskit.transpiler.passes.calibration.rzx_builder.RZXCalibrationBuilder") + +Creates calibrations for RZXGate(theta) by stretching and compressing Gaussian square pulses in the CX gate. + +The `RZXCalibrationBuilderNoEcho` is a variation of the [`RZXCalibrationBuilder`](qiskit.transpiler.passes.RZXCalibrationBuilder "qiskit.transpiler.passes.RZXCalibrationBuilder") pass that creates calibrations for the cross-resonance pulses without inserting the echo pulses in the pulse schedule. This enables exposing the echo in the cross-resonance sequence as gates so that the transpiler can simplify them. The `RZXCalibrationBuilderNoEcho` only supports the hardware-native direction of the CX gate. + +Initializes a RZXGate calibration builder. + +**Parameters** + +* **instruction\_schedule\_map** – The `InstructionScheduleMap` object representing the default pulse calibrations for the target backend +* **verbose** – Set True to raise a user warning when RZX schedule cannot be built. +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `instruction_schedule_map` and this are specified then this argument will take precedence and `instruction_schedule_map` will be ignored. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Instruction schedule map is not provided. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### get\_calibration + + + +`get_calibration(node_op, qubits)` + +Builds the calibration schedule for the RZXGate(theta) without echos. + +**Parameters** + +* **node\_op** (*CircuitInst*) – Instruction of the RZXGate(theta). I.e. params\[0] is theta. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of qubits for which to get the schedules. The first qubit is the control and the second is the target. + +**Returns** + +The calibration schedule for the RZXGate(theta). + +**Return type** + +schedule + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if rotation angle is not assigned. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the control and target qubits cannot be identified, or the backend does not natively support the specified direction of the cx. +* **CalibrationNotAvailable** – RZX schedule cannot be built for input node. + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### rescale\_cr\_inst + + + +`static rescale_cr_inst(instruction, theta, sample_mult=16)` + +A builder macro to play stretched pulse. + +**Parameters** + +* **instruction** ([*Play*](qiskit.pulse.instructions.Play "qiskit.pulse.instructions.play.Play")) – The instruction from which to create a new shortened or lengthened pulse. +* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – desired angle, pi/2 is assumed to be the angle that the pulse in the given play instruction implements. +* **sample\_mult** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – All pulses must be a multiple of sample\_mult. + +**Returns** + +Duration of stretched pulse. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if rotation angle is not assigned. + +**Return type** + +[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the calibration adder pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to schedule. + +**Returns** + +A DAG with calibrations added to it. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### supported + + + +`supported(node_op, qubits)` + +Determine if a given node supports the calibration. + +**Parameters** + +* **node\_op** ([*Instruction*](qiskit.circuit.Instruction "qiskit.circuit.instruction.Instruction")) – Target instruction object. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Integer qubit indices to check. + +**Returns** + +Return `True` is calibration can be provided. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveBarriers.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveBarriers.md new file mode 100644 index 00000000000..a4249a78175 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveBarriers.md @@ -0,0 +1,124 @@ +--- +title: RemoveBarriers +description: API reference for qiskit.transpiler.passes.RemoveBarriers +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RemoveBarriers +--- + +# RemoveBarriers + + + +`qiskit.transpiler.passes.RemoveBarriers(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/remove_barriers.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Return a circuit with any barrier removed. + +This transformation is not semantics preserving. + +**Example** + +```python +from qiskit import QuantumCircuit +from qiskit.transpiler.passes import RemoveBarriers + +circuit = QuantumCircuit(1) +circuit.x(0) +circuit.barrier() +circuit.h(0) + +circuit = RemoveBarriers()(circuit) +circuit.draw('mpl') +``` + +![../\_images/qiskit-transpiler-passes-RemoveBarriers-1.png](/images/api/qiskit/0.46/qiskit-transpiler-passes-RemoveBarriers-1.png) + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the RemoveBarriers pass on dag. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md new file mode 100644 index 00000000000..dbff6dac4d6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure.md @@ -0,0 +1,115 @@ +--- +title: RemoveDiagonalGatesBeforeMeasure +description: API reference for qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure +--- + +# RemoveDiagonalGatesBeforeMeasure + + + +`qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/remove_diagonal_gates_before_measure.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Remove diagonal gates (including diagonal 2Q gates) before a measurement. + +Transpiler pass to remove diagonal gates (like RZ, T, Z, etc) before a measurement. Including diagonal 2Q gates. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the RemoveDiagonalGatesBeforeMeasure pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveFinalMeasurements.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveFinalMeasurements.md new file mode 100644 index 00000000000..1290c6effa1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveFinalMeasurements.md @@ -0,0 +1,117 @@ +--- +title: RemoveFinalMeasurements +description: API reference for qiskit.transpiler.passes.RemoveFinalMeasurements +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RemoveFinalMeasurements +--- + +# RemoveFinalMeasurements + + + +`qiskit.transpiler.passes.RemoveFinalMeasurements(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/remove_final_measurements.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Remove final measurements and barriers at the end of a circuit. + +This pass removes final barriers and final measurements, as well as all unused classical registers and bits they are connected to. Measurements and barriers are considered final if they are followed by no other operations (aside from other measurements or barriers.) + +Classical registers are removed iff they reference at least one bit that has become unused by the circuit as a result of the operation, and all of their other bits are also unused. Separately, classical bits are removed iff they have become unused by the circuit as a result of the operation, or they appear in a removed classical register, but do not appear in a classical register that will remain. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the RemoveFinalMeasurements pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveResetInZeroState.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveResetInZeroState.md new file mode 100644 index 00000000000..bc6e9e5e98d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.RemoveResetInZeroState.md @@ -0,0 +1,113 @@ +--- +title: RemoveResetInZeroState +description: API reference for qiskit.transpiler.passes.RemoveResetInZeroState +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.RemoveResetInZeroState +--- + +# RemoveResetInZeroState + + + +`qiskit.transpiler.passes.RemoveResetInZeroState(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/remove_reset_in_zero_state.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Remove reset gate when the qubit is in zero state. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the RemoveResetInZeroState pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the DAG to be optimized. + +**Returns** + +the optimized DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md new file mode 100644 index 00000000000..97c2ebc6fe9 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ResetAfterMeasureSimplification.md @@ -0,0 +1,103 @@ +--- +title: ResetAfterMeasureSimplification +description: API reference for qiskit.transpiler.passes.ResetAfterMeasureSimplification +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ResetAfterMeasureSimplification +--- + +# ResetAfterMeasureSimplification + + + +`qiskit.transpiler.passes.ResetAfterMeasureSimplification(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/reset_after_measure_simplification.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +This pass replaces reset after measure with a conditional X gate. + +This optimization is suitable for use on IBM Quantum systems where the reset operation is performed by a measurement followed by a conditional x-gate. It might not be desirable on other backends if reset is implemented differently. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the pass on a dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreLayout.md new file mode 100644 index 00000000000..eae67a11425 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreLayout.md @@ -0,0 +1,213 @@ +--- +title: SabreLayout +description: API reference for qiskit.transpiler.passes.SabreLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SabreLayout +--- + +# SabreLayout + + + +`qiskit.transpiler.passes.SabreLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/sabre_layout.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Choose a Layout via iterative bidirectional routing of the input circuit. + +Starting with a random initial Layout, the algorithm does a full routing of the circuit (via the routing\_pass method) to end up with a final\_layout. This final\_layout is then used as the initial\_layout for routing the reverse circuit. The algorithm iterates a number of times until it finds an initial\_layout that reduces full routing cost. + +This method exploits the reversibility of quantum circuits, and tries to include global circuit information in the choice of initial\_layout. + +By default, this pass will run both layout and routing and will transform the circuit so that the layout is applied to the input dag (meaning that the output circuit will have ancilla qubits allocated for unused qubits on the coupling map and the qubits will be reordered to match the mapped physical qubits) and then routing will be applied (inserting `AnalysisPass` objects and just find an initial layout and set that on the property set. This is done because by default the pass will run parallel seed trials with different random seeds for selecting the random initial layout and then selecting the routed output which results in the least number of swap gates needed. + +You can use the `routing_pass` argument to have this pass operate as a typical layout pass. When specified this will use the specified routing pass to select an initial layout only and will not run multiple seed trials. + +In addition to starting with a random initial Layout the pass can also take in an additional list of starting layouts which will be used for additional trials. If the `sabre_starting_layouts` is present in the property set when this pass is run, that will be used for additional trials. There will still be `layout_trials` of full random starting layouts run and the contents of `sabre_starting_layouts` will be run in addition to those. The output which results in the lowest amount of swap gates (whether from the random trials or the property set starting point) will be used. The value for this property set field should be a list of [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") objects representing the starting layouts to use. If a virtual qubit is missing from an [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object in the list a random qubit will be selected. + +## Property Set Fields Read + +**`sabre_starting_layouts` (`list[Layout]`)** + +An optional list of [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") objects to use for additional layout trials. This is in addition to the full random trials specified with the `layout_trials` argument. + +## Property Set Values Written + +**`layout` ([`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout"))** + +The chosen initial mapping of virtual to physical qubits, including the ancilla allocation. + +**`final_layout` ([`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout"))** + +A permutation of how swaps have been applied to the input qubits at the end of the circuit. + +**References:** + +\[1] Li, Gushu, Yufei Ding, and Yuan Xie. “Tackling the qubit mapping problem for NISQ-era quantum devices.” ASPLOS 2019. [arXiv:1809.02573](https://arxiv.org/pdf/1809.02573.pdf) + +SabreLayout initializer. + +**param coupling\_map** + +directed graph representing a coupling map. + +**type coupling\_map** + +Union\[CouplingMap, Target] + +**param routing\_pass** + +the routing pass to use while iterating. If specified this pass operates as an [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.AnalysisPass") and will only populate the `layout` field in the property set and the input dag is returned unmodified. This argument is mutually exclusive with the `swap_trials` and the `layout_trials` arguments and if this is specified at the same time as either argument an error will be raised. + +**type routing\_pass** + +BasePass + +**param seed** + +seed for setting a random first trial layout. + +**type seed** + +int + +**param max\_iterations** + +number of forward-backward iterations. + +**type max\_iterations** + +int + +**param swap\_trials** + +The number of trials to run of [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap") for each iteration. This is equivalent to the `trials` argument on [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap"). If this is not specified (and `routing_pass` isn’t set) by default the number of physical CPUs on your local system will be used. For reproducibility between environments it is best to set this to an explicit number because the output will potentially depend on the number of trials run. This option is mutually exclusive with the `routing_pass` argument and an error will be raised if both are used. + +**type swap\_trials** + +int + +**param layout\_trials** + +The number of random seed trials to run layout with. When > 1 the trial that resuls in the output with the fewest swap gates will be selected. If this is not specified (and `routing_pass` is not set) then the number of local physical CPUs will be used as the default value. This option is mutually exclusive with the `routing_pass` argument and an error will be raised if both are used. + +**type layout\_trials** + +int + +**param skip\_routing** + +If this is set `True` and `routing_pass` is not used then routing will not be applied to the output circuit. Only the layout will be set in the property set. This is a tradeoff to run custom routing with multiple layout trials, as using this option will cause SabreLayout to run the routing stage internally but not use that result. + +**type skip\_routing** + +bool + +**raises TranspilerError** + +If both `routing_pass` and `swap_trials` or + +**raises both `routing_pass` and `layout_trials` are specified** + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the SabreLayout pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to find layout for. + +**Returns** + +**The output dag if swap mapping was run** + +(otherwise the input dag is returned unmodified). + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if dag wider than self.coupling\_map + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabrePreLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabrePreLayout.md new file mode 100644 index 00000000000..9bd5a6555b6 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabrePreLayout.md @@ -0,0 +1,171 @@ +--- +title: SabrePreLayout +description: API reference for qiskit.transpiler.passes.SabrePreLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SabrePreLayout +--- + +# SabrePreLayout + + + +`qiskit.transpiler.passes.SabrePreLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/sabre_pre_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Choose a starting layout to use for additional Sabre layout trials. + +## Property Set Values Written + +**`sabre_starting_layouts` (`list[Layout]`)** + +An optional list of [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") objects to use for additional Sabre layout trials. + +SabrePreLayout initializer. + +The pass works by augmenting the coupling map with more and more “extra” edges until VF2 succeeds to find a perfect graph isomorphism. More precisely, the augmented coupling map contains edges between nodes that are within a given distance `d` in the original coupling map, and the value of `d` is increased until an isomorphism is found. + +Intuitively, a better layout involves fewer extra edges. The pass also optionally minimizes the number of extra edges involved in the layout until a local minimum is found. This involves removing extra edges and running VF2 to see if an isomorphism still exists. + +**param coupling\_map** + +directed graph representing the original coupling map or a target modelling the backend (including its connectivity). + +**type coupling\_map** + +Union\[CouplingMap, Target] + +**param max\_distance** + +the maximum distance to consider for augmented coupling maps. + +**type max\_distance** + +int + +**param error\_rate** + +the error rate to assign to the “extra” edges. A non-zero error rate prioritizes VF2 to choose original edges over extra edges. + +**type error\_rate** + +float + +**param max\_trials\_vf2** + +specifies the maximum number of VF2 trials. A larger number allows VF2 to explore more layouts, eventually choosing the one with the smallest error rate. + +**type max\_trials\_vf2** + +int + +**param call\_limit\_vf2** + +limits each call to VF2 by bounding the number of VF2 state visits. + +**type call\_limit\_vf2** + +int + +**param improve\_layout** + +whether to improve the layout by minimizing the number of extra edges involved. This might be time-consuming as this requires additional VF2 calls. + +**type improve\_layout** + +bool + +**raises TranspilerError** + +At runtime, if neither `coupling_map` or `target` are provided. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the SabrePreLayout pass on dag. + +The discovered starting layout is written to the property set value `sabre_starting_layouts`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to create starting layout for. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreSwap.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreSwap.md new file mode 100644 index 00000000000..5ae0a1a749d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SabreSwap.md @@ -0,0 +1,178 @@ +--- +title: SabreSwap +description: API reference for qiskit.transpiler.passes.SabreSwap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SabreSwap +--- + +# SabreSwap + + + +`qiskit.transpiler.passes.SabreSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/routing/sabre_swap.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Map input circuit onto a backend topology via insertion of SWAPs. + +Implementation of the SWAP-based heuristic search from the SABRE qubit mapping paper \[1] (Algorithm 1). The heuristic aims to minimize the number of lossy SWAPs inserted and the depth of the circuit. + +This algorithm starts from an initial layout of virtual qubits onto physical qubits, and iterates over the circuit DAG until all gates are exhausted, inserting SWAPs along the way. It only considers 2-qubit gates as only those are germane for the mapping problem (it is assumed that 3+ qubit gates are already decomposed). + +In each iteration, it will first check if there are any gates in the `front_layer` that can be directly applied. If so, it will apply them and remove them from `front_layer`, and replenish that layer with new gates if possible. Otherwise, it will try to search for SWAPs, insert the SWAPs, and update the mapping. + +The search for SWAPs is restricted, in the sense that we only consider physical qubits in the neighborhood of those qubits involved in `front_layer`. These give rise to a `swap_candidate_list` which is scored according to some heuristic cost function. The best SWAP is implemented and `current_layout` updated. + +This transpiler pass adds onto the SABRE algorithm in that it will run multiple trials of the algorithm with different seeds. The best output, determined by the trial with the least amount of SWAPed inserted, will be selected from the random trials. + +**References:** + +\[1] Li, Gushu, Yufei Ding, and Yuan Xie. “Tackling the qubit mapping problem for NISQ-era quantum devices.” ASPLOS 2019. [arXiv:1809.02573](https://arxiv.org/pdf/1809.02573.pdf) + +SabreSwap initializer. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – CouplingMap of the target backend. +* **heuristic** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The type of heuristic to use when deciding best swap strategy (‘basic’ or ‘lookahead’ or ‘decay’). +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – random seed used to tie-break among candidate swaps. +* **fake\_run** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if true, it only pretend to do routing, i.e., no swap is effectively added. +* **trials** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of seed trials to run sabre with. These will be run in parallel (unless the PassManager is already running in parallel). If not specified this defaults to the number of physical CPUs on the local system. For reproducible results it is recommended that you set this explicitly, as the output will be deterministic for a fixed number of trials. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the specified heuristic is not valid. + +Additional Information: + +> The search space of possible SWAPs on physical qubits is explored by assigning a score to the layout that would result from each SWAP. The goodness of a layout is evaluated based on how viable it makes the remaining virtual gates that must be applied. A few heuristic cost functions are supported +> +> * ‘basic’: +> +> The sum of distances for corresponding physical qubits of interacting virtual qubits in the front\_layer. +> +> $$ +> H_{basic} = \sum_{gate \in F} D[\pi(gate.q_1)][\pi(gate.q2)] +> $$ +> +> * ‘lookahead’: +> +> This is the sum of two costs: first is the same as the basic cost. Second is the basic cost but now evaluated for the extended set as well (i.e. $|E|$ number of upcoming successors to gates in front\_layer F). This is weighted by some amount EXTENDED\_SET\_WEIGHT (W) to signify that upcoming gates are less important that the front\_layer. +> +> $$ +> H_{decay}=\frac{1}{\left|{F}\right|}\sum_{gate \in F} D[\pi(gate.q_1)][\pi(gate.q2)] +> + W*\frac{1}{\left|{E}\right|} \sum_{gate \in E} D[\pi(gate.q_1)][\pi(gate.q2)] +> $$ +> +> * ‘decay’: +> +> This is the same as ‘lookahead’, but the whole cost is multiplied by a decay factor. This increases the cost if the SWAP that generated the trial layout was recently used (i.e. it penalizes increase in depth). +> +> $$ +> H_{decay} = max(decay(SWAP.q_1), decay(SWAP.q_2)) { +> \frac{1}{\left|{F}\right|} \sum_{gate \in F} D[\pi(gate.q_1)][\pi(gate.q2)]\\ +> + W *\frac{1}{\left|{E}\right|} \sum_{gate \in E} D[\pi(gate.q_1)][\pi(gate.q2)] +> } +> $$ + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the SabreSwap pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the directed acyclic graph to be mapped. + +**Returns** + +A dag mapped to be compatible with the coupling\_map. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the coupling map or the layout are not +* **compatible with the DAG**\*\*, or \*\***if the coupling\_map=None** – + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SetIOLatency.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SetIOLatency.md new file mode 100644 index 00000000000..e72663345e8 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SetIOLatency.md @@ -0,0 +1,116 @@ +--- +title: SetIOLatency +description: API reference for qiskit.transpiler.passes.SetIOLatency +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SetIOLatency +--- + +# SetIOLatency + + + +`qiskit.transpiler.passes.SetIOLatency(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/scheduling/set_io_latency.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Set IOLatency information to the input circuit. + +The `clbit_write_latency` and `conditional_latency` are added to the property set of pass manager. This information can be shared among the passes that perform scheduling on instructions acting on classical registers. + +Once these latencies are added to the property set, this information is also copied to the output circuit object as protected attributes, so that it can be utilized outside the transpilation, for example, the timeline visualization can use latency to accurately show time occupation by instructions on the classical registers. + +Create pass with latency information. + +**Parameters** + +* **clbit\_write\_latency** – A control flow constraints. Because standard superconducting quantum processor implement dispersive QND readout, the actual data transfer to the clbit happens after the round-trip stimulus signal is buffered and discriminated into quantum state. The interval `[t0, t0 + clbit_write_latency]` is regarded as idle time for clbits associated with the measure instruction. This defaults to 0 dt which is identical to Qiskit Pulse scheduler. +* **conditional\_latency** – A control flow constraints. This value represents a latency of reading a classical register for the conditional operation. The gate operation occurs after this latency. This appears as a delay in front of the DAGOpNode of the gate. This defaults to 0 dt. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Add IO latency information. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – Input DAG circuit. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SetLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SetLayout.md new file mode 100644 index 00000000000..424bc58d081 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SetLayout.md @@ -0,0 +1,126 @@ +--- +title: SetLayout +description: API reference for qiskit.transpiler.passes.SetLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SetLayout +--- + +# SetLayout + + + +`qiskit.transpiler.passes.SetLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/set_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Set the `layout` property to the given layout. + +This pass associates a physical qubit (int) to each virtual qubit of the circuit (Qubit) in increasing order. + +SetLayout initializer. + +**Parameters** + +**layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout") *or List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – + +the layout to set. It can be: + +* a `Layout` instance: sets that layout. +* a list of integers: takes the index in the list as the physical position in which the virtual qubit is going to be mapped. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the SetLayout pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to map. + +**Returns** + +the original DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Size.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Size.md new file mode 100644 index 00000000000..7af39522547 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Size.md @@ -0,0 +1,107 @@ +--- +title: Size +description: API reference for qiskit.transpiler.passes.Size +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Size +--- + +# Size + + + +`qiskit.transpiler.passes.Size(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/size.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Calculate the size of a DAG circuit. + +The result is saved in `property_set['size']` as an integer. + +**Parameters** + +**recurse** – whether to allow recursion into control flow. If this is `False` (default), the pass will throw an error when control flow is present, to avoid returning a number with little meaning. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Size pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaev.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaev.md new file mode 100644 index 00000000000..41956f4a5a2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaev.md @@ -0,0 +1,206 @@ +--- +title: SolovayKitaev +description: API reference for qiskit.transpiler.passes.SolovayKitaev +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SolovayKitaev +--- + +# SolovayKitaev + + + +`qiskit.transpiler.passes.SolovayKitaev(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Approximately decompose 1q gates to a discrete basis using the Solovay-Kitaev algorithm. + +The Solovay-Kitaev theorem \[1] states that any single qubit gate can be approximated to arbitrary precision by a set of fixed single-qubit gates, if the set generates a dense subset in $SU(2)$. This is an important result, since it means that any single-qubit gate can be expressed in terms of a discrete, universal gate set that we know how to implement fault-tolerantly. Therefore, the Solovay-Kitaev algorithm allows us to take any non-fault tolerant circuit and rephrase it in a fault-tolerant manner. + +This implementation of the Solovay-Kitaev algorithm is based on \[2]. + +For example, the following circuit + +```python + ┌─────────┐ +q_0: ┤ RX(0.8) ├ + └─────────┘ +``` + +can be decomposed into + +```python +global phase: 7π/8 + ┌───┐┌───┐┌───┐ +q_0: ┤ H ├┤ T ├┤ H ├ + └───┘└───┘└───┘ +``` + +with an L2-error of approximately 0.01. + +**Examples** + +Per default, the basis gate set is `["t", "tdg", "h"]`: + +```python +import numpy as np +from qiskit.circuit import QuantumCircuit +from qiskit.transpiler.passes.synthesis import SolovayKitaev +from qiskit.quantum_info import Operator + +circuit = QuantumCircuit(1) +circuit.rx(0.8, 0) + +print("Original circuit:") +print(circuit.draw()) + +skd = SolovayKitaev(recursion_degree=2) + +discretized = skd(circuit) + +print("Discretized circuit:") +print(discretized.draw()) + +print("Error:", np.linalg.norm(Operator(circuit).data - Operator(discretized).data)) +``` + +```python +Original circuit: + ┌─────────┐ +q: ┤ Rx(0.8) ├ + └─────────┘ +Discretized circuit: +global phase: 7π/8 + ┌───┐┌───┐┌───┐ +q: ┤ H ├┤ T ├┤ H ├ + └───┘└───┘└───┘ +Error: 2.828408279166474 +``` + +For individual basis gate sets, the `generate_basic_approximations` function can be used: + +```python +from qiskit.synthesis import generate_basic_approximations +from qiskit.transpiler.passes import SolovayKitaev + +basis = ["s", "sdg", "t", "tdg", "z", "h"] +approx = generate_basic_approximations(basis, depth=3) + +skd = SolovayKitaev(recursion_degree=2, basic_approximations=approx) +``` + +**References** + +**\[1]: Kitaev, A Yu (1997). Quantum computations: algorithms and error correction.** + +Russian Mathematical Surveys. 52 (6): 1191–1249. [Online](https://iopscience.iop.org/article/10.1070/RM1997v052n06ABEH002155). + +**\[2]: Dawson, Christopher M.; Nielsen, Michael A. (2005) The Solovay-Kitaev Algorithm.** + +[arXiv:quant-ph/0505030](https://arxiv.org/abs/quant-ph/0505030). + +**Parameters** + +* **recursion\_degree** – The recursion depth for the Solovay-Kitaev algorithm. A larger recursion depth increases the accuracy and length of the decomposition. +* **basic\_approximations** – The basic approximations for the finding the best discrete decomposition at the root of the recursion. If a string, it specifies the `.npy` file to load the approximations from. If a dictionary, it contains `{label: SO(3)-matrix}` pairs. If None, a default based on the H, T and Tdg gates up to combinations of depth 10 is generated. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the `SolovayKitaev` pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – The input dag. + +**Returns** + +Output dag with 1q gates synthesized in the discrete target basis. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if a gates does not have to\_matrix + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaevSynthesis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaevSynthesis.md new file mode 100644 index 00000000000..662da059c88 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.SolovayKitaevSynthesis.md @@ -0,0 +1,173 @@ +--- +title: SolovayKitaevSynthesis +description: API reference for qiskit.transpiler.passes.SolovayKitaevSynthesis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.SolovayKitaevSynthesis +--- + +# SolovayKitaevSynthesis + + + +`qiskit.transpiler.passes.SolovayKitaevSynthesis`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py "view source code") + +Bases: [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") + +A Solovay-Kitaev Qiskit unitary synthesis plugin. + +This plugin is invoked by [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") when the `unitary_synthesis_method` parameter is set to `"sk"`. + +This plugin supports customization and additional parameters can be passed to the plugin by passing a dictionary as the `unitary_synthesis_plugin_config` parameter of the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function. + +Supported parameters in the dictionary: + +**basis\_approximations (str | dict):** + +The basic approximations for the finding the best discrete decomposition at the root of the recursion. If a string, it specifies the `.npy` file to load the approximations from. If a dictionary, it contains `{label: SO(3)-matrix}` pairs. If None, a default based on the specified `basis_gates` and `depth` is generated. + +**basis\_gates (list):** + +A list of strings specifying the discrete basis gates to decompose to. If None, defaults to `["h", "t", "tdg"]`. + +**depth (int):** + +The gate-depth of the basic approximations. All possible, unique combinations of the basis gates up to length `depth` are considered. If None, defaults to 10. + +**recursion\_degree (int):** + +The number of times the decomposition is recursively improved. If None, defaults to 3. + +## Attributes + + + +### max\_qubits + +Maximum number of supported qubits is `1`. + + + +### min\_qubits + +Minimum number of supported qubits is `1`. + + + +### supported\_bases + +The plugin does not support bases for synthesis. + + + +### supports\_basis\_gates + +The plugin does not support basis gates. By default it synthesis to the `["h", "t", "tdg"]` gate basis. + + + +### supports\_coupling\_map + +The plugin does not support coupling maps. + + + +### supports\_gate\_errors + +The plugin does not support gate errors. + + + +### supports\_gate\_errors\_by\_qubit + +Return whether the plugin supports taking `gate_errors_by_qubit` + +This differs from `supports_gate_errors`/`gate_errors` by using a different view of the same data. Instead of being keyed by gate name this is keyed by qubit and uses [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to represent gates (instead of gate names). + +`gate_errors_by_qubit` will be a dictionary in the form of `{(qubits,): [Gate, error]}`. For example: + +```python +{ +(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], +(0, 1): [CXGate(): 0.012012477900732316] +} +``` + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate errors on every gate for each qubit. The gate error rates reported in `gate_errors` are provided by the target device `Backend` object and the exact meaning might be different depending on the backend. + +This defaults to False + + + +### supports\_gate\_lengths + +The plugin does not support gate lengths. + + + +### supports\_gate\_lengths\_by\_qubit + +Return whether the plugin supports taking `gate_lengths_by_qubit` + +This differs from `supports_gate_lengths`/`gate_lengths` by using a different view of the same data. Instead of being keyed by gate name this is keyed by qubit and uses [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to represent gates (instead of gate names) + +`gate_lengths_by_qubit` will be a dictionary in the form of `{(qubits,): [Gate, length]}`. For example: + +```python +{ +(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], +(0, 1): [CXGate(): 0.012012477900732316] +} +``` + +where the `length` value is in units of seconds. + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate lengths on every gate for each qubit. + +This defaults to False + + + +### supports\_natural\_direction + +The plugin does not support natural direction, it does not assume bidirectional two qubit gates. + + + +### supports\_pulse\_optimize + +The plugin does not support optimization of pulses. + + + +### supports\_target + +Whether the plugin supports taking `target` as an option + +`target` will be a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the target device for the output of the synthesis pass. + +By default this will be `False` since the plugin interface predates the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class. If a plugin returns `True` for this attribute, it is expected that the plugin will use the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") instead of the values passed if any of `supports_gate_lengths`, `supports_gate_errors`, `supports_coupling_map`, and `supports_basis_gates` are set (although ideally all those parameters should contain duplicate information). + +## Methods + +### run + + + +`run(unitary, **options)` + +Run synthesis for the given unitary matrix + +**Parameters** + +* **unitary** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – The unitary matrix to synthesize to a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object +* **options** – The optional kwargs that are passed based on the output the `support_*` methods on the class. Refer to the documentation for these methods on [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") to see what the keys and values are. + +**Returns** + +The dag circuit representation of the unitary. Alternatively, you can return a tuple of the form `(dag, wires)` where `dag` is the dag circuit representation of the circuit representation of the unitary and `wires` is the mapping wires to use for [`qiskit.dagcircuit.DAGCircuit.substitute_node_with_dag()`](qiskit.dagcircuit.DAGCircuit#substitute_node_with_dag "qiskit.dagcircuit.DAGCircuit.substitute_node_with_dag"). If you return a tuple and `wires` is `None` this will behave just as if only a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") was returned. Additionally if this returns `None` no substitution will be made. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.StochasticSwap.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.StochasticSwap.md new file mode 100644 index 00000000000..ae71492710b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.StochasticSwap.md @@ -0,0 +1,139 @@ +--- +title: StochasticSwap +description: API reference for qiskit.transpiler.passes.StochasticSwap +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.StochasticSwap +--- + +# StochasticSwap + + + +`qiskit.transpiler.passes.StochasticSwap(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/routing/stochastic_swap.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Map a DAGCircuit onto a coupling\_map adding swap gates. + +Uses a randomized algorithm. + +**Notes** + +1. Measurements may occur and be followed by swaps that result in repeated measurement of the same qubit. Near-term experiments cannot implement these circuits, so some care is required when using this mapper with experimental backend targets. +2. We do not use the fact that the input state is zero to simplify the circuit. + +StochasticSwap initializer. + +The coupling map is a connected graph + +If these are not satisfied, the behavior is undefined. + +**Parameters** + +* **coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – Directed graph representing a coupling map. +* **trials** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – maximum number of iterations to attempt +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – seed for random number generator +* **fake\_run** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – if true, it will only pretend to do routing, i.e., no swap is effectively added. +* **initial\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – starting layout at beginning of pass. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the StochasticSwap pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to map. + +**Returns** + +A mapped DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +* [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the coupling map or the layout are not +* **compatible with the DAG**\*\*, or \*\***if the coupling\_map=None** – + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.TemplateOptimization.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TemplateOptimization.md new file mode 100644 index 00000000000..df83c02c1b3 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TemplateOptimization.md @@ -0,0 +1,122 @@ +--- +title: TemplateOptimization +description: API reference for qiskit.transpiler.passes.TemplateOptimization +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.TemplateOptimization +--- + +# TemplateOptimization + + + +`qiskit.transpiler.passes.TemplateOptimization(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/optimization/template_optimization.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Class for the template optimization pass. + +**Parameters** + +* **template\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*()]*) – list of the different template circuit to apply. +* **heuristics\_backward\_param** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – \[length, survivor] Those are the parameters for applying heuristics on the backward part of the algorithm. This part of the algorithm creates a tree of matching scenario. This tree grows exponentially. The heuristics evaluate which scenarios have the longest match and keep only those. The length is the interval in the tree for cutting it and survivor is the number of scenarios that are kept. We advise to use l=3 and s=1 to have serious time advantage. We remind that the heuristics implies losing a part of the maximal matches. Check reference for more details. +* **heuristics\_qubits\_param** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – \[length] The heuristics for the qubit choice make guesses from the dag dependency of the circuit in order to limit the number of qubit configurations to explore. The length is the number of successors or not predecessors that will be explored in the dag dependency of the circuit, each qubits of the nodes are added to the set of authorized qubits. We advise to use length=1. Check reference for more details. +* **user\_cost\_dict** (*Dict\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – quantum cost dictionary passed to TemplateSubstitution to configure its behavior. This will override any default values if None is not given. The key is the name of the gate and the value its quantum cost. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG circuit. + +**Returns** + +optimized DAG circuit. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the template has not the right form or if the output circuit acts differently as the input circuit. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.TimeUnitConversion.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TimeUnitConversion.md new file mode 100644 index 00000000000..c8fb808f87e --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TimeUnitConversion.md @@ -0,0 +1,132 @@ +--- +title: TimeUnitConversion +description: API reference for qiskit.transpiler.passes.TimeUnitConversion +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.TimeUnitConversion +--- + +# TimeUnitConversion + + + +`qiskit.transpiler.passes.TimeUnitConversion(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/time_unit_conversion.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Choose a time unit to be used in the following time-aware passes, and make all circuit time units consistent with that. + +This pass will add a [`Instruction.duration`](qiskit.circuit.Instruction#duration "qiskit.circuit.Instruction.duration") metadata to each op whose duration is known which will be used by subsequent scheduling passes for scheduling. + +If `dt` (in seconds) is known to transpiler, the unit `'dt'` is chosen. Otherwise, the unit to be selected depends on what units are used in delays and instruction durations: + +* `'s'`: if they are all in SI units. +* `'dt'`: if they are all in the unit `'dt'`. +* raise error: if they are a mix of SI units and `'dt'`. + +TimeUnitAnalysis initializer. + +**Parameters** + +* **inst\_durations** ([*InstructionDurations*](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations")) – A dictionary of durations of instructions. +* **target** – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `inst_durations` and `target` are specified then this argument will take precedence and `inst_durations` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the TimeUnitAnalysis pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to be checked. + +**Returns** + +DAG with consistent timing and op nodes annotated with duration. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the units are not unifiable + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.TranslateParameterizedGates.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TranslateParameterizedGates.md new file mode 100644 index 00000000000..222de73e818 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TranslateParameterizedGates.md @@ -0,0 +1,174 @@ +--- +title: TranslateParameterizedGates +description: API reference for qiskit.transpiler.passes.TranslateParameterizedGates +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.TranslateParameterizedGates +--- + +# TranslateParameterizedGates + + + +`qiskit.transpiler.passes.TranslateParameterizedGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/basis/translate_parameterized.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Translate parameterized gates to a supported basis set. + +Once a parameterized instruction is found that is not in the `supported_gates` list, the instruction is decomposed one level and the parameterized sub-blocks are recursively decomposed. The recursion is stopped once all parameterized gates are in `supported_gates`, or if a gate has no definition and a translation to the basis is attempted (this might happen e.g. for the `UGate` if it’s not in the specified gate list). + +**Example** + +The following, multiply nested circuit: + +```python +from qiskit.circuit import QuantumCircuit, ParameterVector +from qiskit.transpiler.passes import TranslateParameterizedGates + +x = ParameterVector("x", 4) +block1 = QuantumCircuit(1) +block1.rx(x[0], 0) + +sub_block = QuantumCircuit(2) +sub_block.cx(0, 1) +sub_block.rz(x[2], 0) + +block2 = QuantumCircuit(2) +block2.ry(x[1], 0) +block2.append(sub_block.to_gate(), [0, 1]) + +block3 = QuantumCircuit(3) +block3.ccx(0, 1, 2) + +circuit = QuantumCircuit(3) +circuit.append(block1.to_gate(), [1]) +circuit.append(block2.to_gate(), [0, 1]) +circuit.append(block3.to_gate(), [0, 1, 2]) +circuit.cry(x[3], 0, 2) + +supported_gates = ["rx", "ry", "rz", "cp", "crx", "cry", "crz"] +unrolled = TranslateParameterizedGates(supported_gates)(circuit) +``` + +is decomposed to: + +```python + ┌──────────┐ ┌──────────┐┌─────────────┐ +q_0: ┤ Ry(x[1]) ├──■──┤ Rz(x[2]) ├┤0 ├─────■────── + ├──────────┤┌─┴─┐└──────────┘│ │ │ +q_1: ┤ Rx(x[0]) ├┤ X ├────────────┤1 circuit-92 ├─────┼────── + └──────────┘└───┘ │ │┌────┴─────┐ +q_2: ─────────────────────────────┤2 ├┤ Ry(x[3]) ├ + └─────────────┘└──────────┘ +``` + +**Parameters** + +* **supported\_gates** – A list of suppported basis gates specified as string. If `None`, a `target` must be provided. +* **equivalence\_library** – The equivalence library to translate the gates. Defaults to the equivalence library of all Qiskit standard gates. +* **target** – A [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") containing the supported operations. If `None`, `supported_gates` must be set. Note that this argument takes precedence over `supported_gates`, if both are set. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If neither of `supported_gates` and `target` are passed. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the transpiler pass. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – The DAG circuit in which the parameterized gates should be unrolled. + +**Returns** + +A DAG where the parameterized gates have been unrolled. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the circuit cannot be unrolled. + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.TrivialLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TrivialLayout.md new file mode 100644 index 00000000000..c6410fbf812 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.TrivialLayout.md @@ -0,0 +1,125 @@ +--- +title: TrivialLayout +description: API reference for qiskit.transpiler.passes.TrivialLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.TrivialLayout +--- + +# TrivialLayout + + + +`qiskit.transpiler.passes.TrivialLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/trivial_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Choose a Layout by assigning `n` circuit qubits to device qubits `0, .., n-1`. + +A pass for choosing a Layout of a circuit onto a Coupling graph, using a simple round-robin order. + +This pass associates a physical qubit (int) to each virtual qubit of the circuit (Qubit) in increasing order. + +Does not assume any ancilla. + +TrivialLayout initializer. + +**Parameters** + +**coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – directed graph representing a coupling map. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if invalid options + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the TrivialLayout pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – DAG to find layout for. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if dag wider than the target backend + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnitarySynthesis.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnitarySynthesis.md new file mode 100644 index 00000000000..22a53c908bc --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnitarySynthesis.md @@ -0,0 +1,135 @@ +--- +title: UnitarySynthesis +description: API reference for qiskit.transpiler.passes.UnitarySynthesis +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.UnitarySynthesis +--- + +# UnitarySynthesis + + + +`qiskit.transpiler.passes.UnitarySynthesis(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/unitary_synthesis.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Synthesize gates according to their basis gates. + +Synthesize unitaries over some basis gates. + +This pass can approximate 2-qubit unitaries given some gate fidelities (either via `backend_props` or `target`). More approximation can be forced by setting a heuristic dial `approximation_degree`. + +**Parameters** + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – List of gate names to target. If this is not specified the `target` argument must be used. If both this and the `target` are specified the value of `target` will be used and this will be ignored. +* **approximation\_degree** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation). Approximation can make the synthesized circuit cheaper at the cost of straying from the original unitary. If None, approximation is done based on gate fidelities. +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – the coupling map of the backend in case synthesis is done on a physical circuit. The directionality of the coupling\_map will be taken into account if `pulse_optimize` is `True`/`None` and `natural_direction` is `True`/`None`. +* **backend\_props** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – Properties of a backend to synthesize for (e.g. gate fidelities). +* **pulse\_optimize** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to optimize pulses during synthesis. A value of `None` will attempt it but fall back if it does not succeed. A value of `True` will raise an error if pulse-optimized synthesis does not succeed. +* **natural\_direction** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether to apply synthesis considering directionality of 2-qubit gates. Only applies when `pulse_optimize` is `True` or `None`. The natural direction is determined by first checking to see whether the coupling map is unidirectional. If there is no coupling map or the coupling map is bidirectional, the gate direction with the shorter duration from the backend properties will be used. If set to True, and a natural direction can not be determined, raises [`TranspilerError`](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError"). If set to None, no exception will be raised if a natural direction can not be determined. +* **synth\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – List of gates to synthesize. If None and `pulse_optimize` is False or None, default to `['unitary']`. If `None` and `pulse_optimize == True`, default to `['unitary', 'swap']` +* **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unitary synthesis method plugin to use. +* **min\_qubits** – The minimum number of qubits in the unitary to synthesize. If this is set and the unitary is less than the specified number of qubits it will not be synthesized. +* **plugin\_config** – Optional extra configuration arguments (as a `dict`) which are passed directly to the specified unitary synthesis plugin. By default, this will have no effect as the default plugin has no extra arguments. Refer to the documentation of your unitary synthesis plugin on how to use this. +* **target** – The optional [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") for the target device the pass is compiling for. If specified this will supersede the values set for `basis_gates`, `coupling_map`, and `backend_props`. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the UnitarySynthesis pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – input dag. + +**Returns** + +Output dag with UnitaryGates synthesized to target basis. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if `method` was specified for the class and is not found in the installed plugins list. The list of installed plugins can be queried with [`unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names") + +**Return type** + +[*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroll3qOrMore.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroll3qOrMore.md new file mode 100644 index 00000000000..fe75b978b50 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroll3qOrMore.md @@ -0,0 +1,124 @@ +--- +title: Unroll3qOrMore +description: API reference for qiskit.transpiler.passes.Unroll3qOrMore +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Unroll3qOrMore +--- + +# Unroll3qOrMore + + + +`qiskit.transpiler.passes.Unroll3qOrMore(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/basis/unroll_3q_or_more.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Recursively expands 3q+ gates until the circuit only contains 2q or 1q gates. + +Initialize the Unroll3qOrMore pass + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The target object representing the compilation target. If specified any multi-qubit instructions in the circuit when the pass is run that are supported by the target device will be left in place. If both this and `basis_gates` are specified only the target will be checked. +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of basis gate names that the target device supports. If specified any gate names in the circuit which are present in this list will not be unrolled. If both this and `target` are specified only the target will be used for checking which gates are supported. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Unroll3qOrMore pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – input dag + +**Returns** + +output dag with maximum node degrees of 2 + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if a 3q+ gate is not decomposable + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollCustomDefinitions.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollCustomDefinitions.md new file mode 100644 index 00000000000..9f47bb9716d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollCustomDefinitions.md @@ -0,0 +1,136 @@ +--- +title: UnrollCustomDefinitions +description: API reference for qiskit.transpiler.passes.UnrollCustomDefinitions +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.UnrollCustomDefinitions +--- + +# UnrollCustomDefinitions + + + +`qiskit.transpiler.passes.UnrollCustomDefinitions(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/basis/unroll_custom_definitions.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Unrolls instructions with custom definitions. + +Unrolls instructions with custom definitions. + +**Parameters** + +* **equivalence\_library** ([*EquivalenceLibrary*](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary")) – The equivalence library which will be used by the BasisTranslator pass. (Instructions in this library will not be unrolled by this pass.) + +* **basis\_gates** (*Optional\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]]*) – Target basis names to unroll to, e.g. `['u3', 'cx']`. Ignored if `target` is also specified. + +* **target** (*Optional\[*[*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")*]*) – + + **The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object corresponding to the compilation** + + target. When specified, any argument specified for `basis_gates` is ignored. + + **min\_qubits (int): The minimum number of qubits for operations in the input** + + dag to translate. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the UnrollCustomDefinitions pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – input dag + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if unable to unroll given the basis due to undefined +* **decomposition rules**\*\* (****such as a bad basis****) or \*\***excessive recursion.** – + +**Returns** + +output unrolled dag + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollForLoops.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollForLoops.md new file mode 100644 index 00000000000..ac595f65867 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.UnrollForLoops.md @@ -0,0 +1,123 @@ +--- +title: UnrollForLoops +description: API reference for qiskit.transpiler.passes.UnrollForLoops +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.UnrollForLoops +--- + +# UnrollForLoops + + + +`qiskit.transpiler.passes.UnrollForLoops(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/utils/unroll_forloops.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +`UnrollForLoops` transpilation pass unrolls for-loops when possible. + +Things like `for x in {0, 3, 4} {rx(x) qr[1];}` will turn into `rx(0) qr[1]; rx(3) qr[1]; rx(4) qr[1];`. + + + The `UnrollForLoops` unrolls only one level of block depth. No inner loop will be considered by `max_target_depth`. + + +**Parameters** + +**max\_target\_depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. Checks if the unrolled block is over a particular subcircuit depth. To disable the check, use `-1` (Default). + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the UnrollForLoops pass on `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the directed acyclic graph to run on. + +**Returns** + +Transformed DAG. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroller.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroller.md new file mode 100644 index 00000000000..dd930f08405 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Unroller.md @@ -0,0 +1,131 @@ +--- +title: Unroller +description: API reference for qiskit.transpiler.passes.Unroller +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Unroller +--- + +# Unroller + + + +`qiskit.transpiler.passes.Unroller(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/basis/unroller.py "view source code") + +Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") + +Unroll a circuit to a given basis. + +Unroll (expand) non-basis, non-opaque instructions recursively to a desired basis, using decomposition rules defined for each instruction. + +Unroller initializer. + + + The class `qiskit.transpiler.passes.basis.unroller.Unroller` is deprecated as of qiskit 0.45.0. It will be removed in the Qiskit 1.0 release. This has been replaced by the BasisTranslator pass. + + +**Parameters** + +* **basis** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] or None*) – Target basis names to unroll to, e.g. \[‘u3’, ‘cx’] . If None, does not unroll any gate. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing the target backend, if both `basis` and this are specified then this argument will take precedence and `basis` will be ignored. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Unroller pass on dag. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – input dag + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if unable to unroll given the basis due to undefined +* **decomposition rules**\*\* (****such as a bad basis****) or \*\***excessive recursion.** – + +**Returns** + +output unrolled dag + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2Layout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2Layout.md new file mode 100644 index 00000000000..c73c716b2ae --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2Layout.md @@ -0,0 +1,137 @@ +--- +title: VF2Layout +description: API reference for qiskit.transpiler.passes.VF2Layout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.VF2Layout +--- + +# VF2Layout + + + +`qiskit.transpiler.passes.VF2Layout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/vf2_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +A pass for choosing a Layout of a circuit onto a Coupling graph, as a subgraph isomorphism problem, solved by VF2++. + +If a solution is found that means there is a “perfect layout” and that no further swap mapping or routing is needed. If a solution is found the layout will be set in the property set as `property_set['layout']`. However, if no solution is found, no `property_set['layout']` is set. The stopping reason is set in `property_set['VF2Layout_stop_reason']` in all the cases and will be one of the values enumerated in `VF2LayoutStopReason` which has the following values: + +> * `"solution found"`: If a perfect layout was found. +> * `"nonexistent solution"`: If no perfect layout was found. +> * `">2q gates in basis"`: If VF2Layout can’t work with basis + +By default, this pass will construct a heuristic scoring map based on the error rates in the provided `target` (or `properties` if `target` is not provided). However, analysis passes can be run prior to this pass and set `vf2_avg_error_map` in the property set with a `ErrorMap` instance. If a value is `NaN` that is treated as an ideal edge For example if an error map is created as: + +```python +from qiskit.transpiler.passes.layout.vf2_utils import ErrorMap + +error_map = ErrorMap(3) +error_map.add_error((0, 0), 0.0024) +error_map.add_error((0, 1), 0.01) +error_map.add_error((1, 1), 0.0032) +``` + +that represents the error map for a 2 qubit target, where the avg 1q error rate is `0.0024` on qubit 0 and `0.0032` on qubit 1. Then the avg 2q error rate for gates that operate on (0, 1) is 0.01 and (1, 0) is not supported by the target. This will be used for scoring if it’s set as the `vf2_avg_error_map` key in the property set when [`VF2Layout`](#qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout") is run. + +Initialize a `VF2Layout` pass instance + +**Parameters** + +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Directed graph representing a coupling map. +* **strict\_direction** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, considers the direction of the coupling map. Default is False. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets the seed of the PRNG. -1 Means no node shuffling. +* **call\_limit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of state visits to attempt in each execution of VF2. +* **time\_limit** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The total time limit in seconds to run `VF2Layout` +* **properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – The backend properties for the backend. If [`readout_error()`](qiskit.providers.models.BackendProperties#readout_error "qiskit.providers.models.BackendProperties.readout_error") is available it is used to score the layout. +* **max\_trials** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of trials to run VF2 to find a layout. If this is not specified the number of trials will be limited based on the number of edges in the interaction graph or the coupling graph (whichever is larger) if no other limits are set. If set to a value \<= 0 no limit on the number of trials will be set. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – A target representing the backend device to run `VF2Layout` on. If specified it will supersede a set value for `properties` and `coupling_map`. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – At runtime, if neither `coupling_map` or `target` are provided. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +run the layout method + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2PostLayout.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2PostLayout.md new file mode 100644 index 00000000000..6258e33d590 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.VF2PostLayout.md @@ -0,0 +1,139 @@ +--- +title: VF2PostLayout +description: API reference for qiskit.transpiler.passes.VF2PostLayout +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.VF2PostLayout +--- + +# VF2PostLayout + + + +`qiskit.transpiler.passes.VF2PostLayout(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/layout/vf2_post_layout.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +A pass for choosing a Layout after transpilation of a circuit onto a Coupling graph, as a subgraph isomorphism problem, solved by VF2++. + +Unlike the [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout") transpiler pass which is designed to find an initial layout for a circuit early in the transpilation pipeline this transpiler pass is designed to try and find a better layout after transpilation is complete. The initial layout phase of the transpiler doesn’t have as much information available as we do after transpilation. This pass is designed to be paired in a similar pipeline as the layout passes. This pass will strip any idle wires from the circuit, use VF2 to find a subgraph in the coupling graph for the circuit to run on with better fidelity and then update the circuit layout to use the new qubits. The algorithm used in this pass is described in [arXiv:2209.15512](https://arxiv.org/abs/2209.15512). + +If a solution is found that means there is a lower error layout available for the circuit. If a solution is found the layout will be set in the property set as `property_set['post_layout']`. However, if no solution is found, no `property_set['post_layout']` is set. The stopping reason is set in `property_set['VF2PostLayout_stop_reason']` in all the cases and will be one of the values enumerated in `VF2PostLayoutStopReason` which has the following values: + +> * `"solution found"`: If a solution was found. +> * `"nonexistent solution"`: If no solution was found. +> * `">2q gates in basis"`: If VF2PostLayout can’t work with basis + +By default, this pass will construct a heuristic scoring map based on the error rates in the provided `target` (or `properties` if `target` is not provided). However, analysis passes can be run prior to this pass and set `vf2_avg_error_map` in the property set with a `ErrorMap` instance. If a value is `NaN` that is treated as an ideal edge For example if an error map is created as: + +```python +from qiskit.transpiler.passes.layout.vf2_utils import ErrorMap + +error_map = ErrorMap(3) +error_map.add_error((0, 0), 0.0024) +error_map.add_error((0, 1), 0.01) +error_map.add_error((1, 1), 0.0032) +``` + +that represents the error map for a 2 qubit target, where the avg 1q error rate is `0.0024` on qubit 0 and `0.0032` on qubit 1. Then the avg 2q error rate for gates that operate on (0, 1) is 0.01 and (1, 0) is not supported by the target. This will be used for scoring if it’s set as the `vf2_avg_error_map` key in the property set when [`VF2PostLayout`](#qiskit.transpiler.passes.VF2PostLayout "qiskit.transpiler.passes.VF2PostLayout") is run. + +Initialize a `VF2PostLayout` pass instance + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – A target representing the backend device to run `VF2PostLayout` on. If specified it will supersede a set value for `properties` and `coupling_map`. +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Directed graph representing a coupling map. +* **properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – The backend properties for the backend. If [`readout_error()`](qiskit.providers.models.BackendProperties#readout_error "qiskit.providers.models.BackendProperties.readout_error") is available it is used to score the layout. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets the seed of the PRNG. -1 Means no node shuffling. +* **call\_limit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of state visits to attempt in each execution of VF2. +* **time\_limit** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The total time limit in seconds to run `VF2PostLayout` +* **strict\_direction** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Whether the pass is configured to follow the strict direction in the coupling graph. If this is set to false, the pass will treat any edge in the coupling graph as a weak edge and the interaction graph will be undirected. For the purposes of evaluating layouts the avg error rate for each qubit and 2q link will be used. This enables the pass to be run prior to basis translation and work with any 1q and 2q operations. However, if `strict_direction=True` the pass expects the input [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object to [`run()`](#qiskit.transpiler.passes.VF2PostLayout.run "qiskit.transpiler.passes.VF2PostLayout.run") to be in the target set of instructions. +* **max\_trials** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of trials to run VF2 to find a layout. A value of `0` (the default) means ‘unlimited’. + +**Raises** + +[**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – At runtime, if neither `coupling_map` or `target` are provided. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +run the layout method + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.ValidatePulseGates.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ValidatePulseGates.md new file mode 100644 index 00000000000..2c392b26f2c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.ValidatePulseGates.md @@ -0,0 +1,132 @@ +--- +title: ValidatePulseGates +description: API reference for qiskit.transpiler.passes.ValidatePulseGates +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.ValidatePulseGates +--- + +# ValidatePulseGates + + + +`qiskit.transpiler.passes.ValidatePulseGates(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/scheduling/alignments/pulse_gate_validation.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Check custom gate length. + +This is a control electronics aware analysis pass. + +Quantum gates (instructions) are often implemented with shaped analog stimulus signals. These signals may be digitally stored in the waveform memory of the control electronics and converted into analog voltage signals by electronic components known as digital to analog converters (DAC). + +In Qiskit SDK, we can define the pulse-level implementation of custom quantum gate instructions, as a [pulse gate](https://docs.quantum-computing.ibm.com/build/pulse), thus user gates should satisfy all waveform memory constraints imposed by the backend. + +This pass validates all attached calibration entries and raises `TranspilerError` to kill the transpilation process if any invalid calibration entry is found. This pass saves users from waiting until job execution time to get an invalid pulse error from the backend control electronics. + +Create new pass. + +**Parameters** + +* **granularity** – Integer number representing the minimum time resolution to define the pulse gate length in units of `dt`. This value depends on the control electronics of your quantum processor. +* **min\_length** – Integer number representing the minimum data point length to define the pulse gate in units of `dt`. This value depends on the control electronics of your quantum processor. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the pulse gate validation attached to `dag`. + +**Parameters** + +**dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – DAG to be validated. + +**Returns** + +DAG with consistent timing and op nodes annotated with duration. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – When pulse gate violate pulse controller constraints. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.Width.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Width.md new file mode 100644 index 00000000000..e135edc3229 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.Width.md @@ -0,0 +1,103 @@ +--- +title: Width +description: API reference for qiskit.transpiler.passes.Width +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.Width +--- + +# Width + + + +`qiskit.transpiler.passes.Width(*args, **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/analysis/width.py "view source code") + +Bases: [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.basepasses.AnalysisPass") + +Calculate the width of a DAG circuit. + +The result is saved in `property_set['width']` as an integer that contains the number of qubits + the number of clbits. + +## Attributes + + + +### is\_analysis\_pass + +Check if the pass is an analysis pass. + +If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + + + +### is\_transformation\_pass + +Check if the pass is a transformation pass. + +If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + +## Methods + +### execute + + + +`execute(passmanager_ir, state, callback=None)` + +Execute optimization task for input Qiskit IR. + +**Parameters** + +* **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")) – Qiskit IR to optimize. +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself. +* **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.12)") *| None*) – A callback function which is caller per execution of optimization task. + +**Returns** + +Optimized Qiskit IR and state of the workflow. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")] + +### name + + + +`name()` + +Name of the pass. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### run + + + +`run(dag)` + +Run the Width pass on dag. + +### update\_status + + + +`update_status(state, run_state)` + +Update workflow status. + +**Parameters** + +* **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update. +* **run\_state** (*RunState*) – Completion status of current task. + +**Returns** + +Updated pass manager state. + +**Return type** + +[*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md new file mode 100644 index 00000000000..09997127db7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.md @@ -0,0 +1,48 @@ +--- +title: HighLevelSynthesisPlugin +description: API reference for qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin +--- + +# HighLevelSynthesisPlugin + + + +`qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/plugin.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Abstract high-level synthesis plugin class. + +This abstract class defines the interface for high-level synthesis plugins. + +## Methods + +### run + + + +`abstract run(high_level_object, coupling_map=None, target=None, qubits=None, **options)` + +Run synthesis for the given Operation. + +**Parameters** + +* **high\_level\_object** ([*Operation*](qiskit.circuit.Operation "qiskit.circuit.Operation")) – The Operation to synthesize to a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object. +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – The coupling map of the backend in case synthesis is done on a physical circuit. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – A target representing the target backend. +* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of qubits over which the operation is defined in case synthesis is done on a physical circuit. +* **options** – Additional method-specific optional kwargs. + +**Returns** + +**The quantum circuit representation of the Operation** + +when successful, and `None` otherwise. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md new file mode 100644 index 00000000000..d9428503746 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager.md @@ -0,0 +1,36 @@ +--- +title: HighLevelSynthesisPluginManager +description: API reference for qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager +--- + +# HighLevelSynthesisPluginManager + + + +`qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/plugin.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Class tracking the installed high-level-synthesis plugins. + +## Methods + +### method + + + +`method(op_name, method_name)` + +Returns the plugin for `op_name` and `method_name`. + +### method\_names + + + +`method_names(op_name)` + +Returns plugin methods for op\_name. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md new file mode 100644 index 00000000000..23e00b3647c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.md @@ -0,0 +1,200 @@ +--- +title: UnitarySynthesisPlugin +description: API reference for qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin +--- + +# UnitarySynthesisPlugin + + + +`qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/plugin.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +Abstract unitary synthesis plugin class + +This abstract class defines the interface for unitary synthesis plugins. + +## Attributes + + + +### max\_qubits + +Return the maximum number of qubits the unitary synthesis plugin supports. + +If the size of the unitary to be synthesized exceeds this value the `default` plugin will be used. If there is no upper bound return `None` and all unitaries (`>= min_qubits` if it’s defined) will be passed to this plugin when it’s enabled. + + + +### min\_qubits + +Return the minimum number of qubits the unitary synthesis plugin supports. + +If the size of the unitary to be synthesized is below this value the `default` plugin will be used. If there is no lower bound return `None` and all unitaries (`<= max_qubits` if it’s defined) will be passed to this plugin when it’s enabled. + + + +### supported\_bases + +Returns a dictionary of supported bases for synthesis + +This is expected to return a dictionary where the key is a string basis and the value is a list of gate names that the basis works in. If the synthesis method doesn’t support multiple bases this should return `None`. For example: + +```python +{ + "XZX": ["rz", "rx"], + "XYX": ["rx", "ry"], +} +``` + +If a dictionary is returned by this method the run kwargs will be passed a parameter `matched_basis` which contains a list of the basis strings (i.e. keys in the dictionary) which match the target basis gate set for the transpilation. If no entry in the dictionary matches the target basis gate set then the `matched_basis` kwarg will be set to an empty list, and a plugin can choose how to deal with the target basis gate set not matching the plugin’s capabilities. + + + +### supports\_basis\_gates + +Return whether the plugin supports taking `basis_gates` + +If this returns `True` the plugin’s `run()` method will be passed a `basis_gates` kwarg with a list of gate names the target backend supports. For example, `['sx', 'x', 'cx', 'id', 'rz']`. + + + +### supports\_coupling\_map + +Return whether the plugin supports taking `coupling_map` + +If this returns `True` the plugin’s `run()` method will receive one kwarg `coupling_map`. The `coupling_map` kwarg will be set to a tuple with the first element being a [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object representing the qubit connectivity of the target backend, the second element will be a list of integers that represent the qubit indices in the coupling map that unitary is on. Note that if the target backend doesn’t have a coupling map set, the `coupling_map` kwarg’s value will be `(None, qubit_indices)`. + + + +### supports\_gate\_errors + +Return whether the plugin supports taking `gate_errors` + +`gate_errors` will be a dictionary in the form of `{gate_name: {(qubit_1, qubit_2): error}}`. For example: + +```python +{ +'sx': {(0,): 0.0006149355812506126, (1,): 0.0006149355812506126}, +'cx': {(0, 1): 0.012012477900732316, (1, 0): 5.191111111111111e-07} +} +``` + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate errors on every gate for each qubit. The gate error rates reported in `gate_errors` are provided by the target device `Backend` object and the exact meaning might be different depending on the backend. + + + +### supports\_gate\_errors\_by\_qubit + +Return whether the plugin supports taking `gate_errors_by_qubit` + +This differs from `supports_gate_errors`/`gate_errors` by using a different view of the same data. Instead of being keyed by gate name this is keyed by qubit and uses [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to represent gates (instead of gate names). + +`gate_errors_by_qubit` will be a dictionary in the form of `{(qubits,): [Gate, error]}`. For example: + +```python +{ +(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], +(0, 1): [CXGate(): 0.012012477900732316] +} +``` + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate errors on every gate for each qubit. The gate error rates reported in `gate_errors` are provided by the target device `Backend` object and the exact meaning might be different depending on the backend. + +This defaults to False + + + +### supports\_gate\_lengths + +Return whether the plugin supports taking `gate_lengths` + +`gate_lengths` will be a dictionary in the form of `{gate_name: {(qubit_1, qubit_2): length}}`. For example: + +```python +{ +'sx': {(0,): 0.0006149355812506126, (1,): 0.0006149355812506126}, +'cx': {(0, 1): 0.012012477900732316, (1, 0): 5.191111111111111e-07} +} +``` + +where the `length` value is in units of seconds. + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate lengths on every gate for each qubit. + + + +### supports\_gate\_lengths\_by\_qubit + +Return whether the plugin supports taking `gate_lengths_by_qubit` + +This differs from `supports_gate_lengths`/`gate_lengths` by using a different view of the same data. Instead of being keyed by gate name this is keyed by qubit and uses [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to represent gates (instead of gate names) + +`gate_lengths_by_qubit` will be a dictionary in the form of `{(qubits,): [Gate, length]}`. For example: + +```python +{ +(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], +(0, 1): [CXGate(): 0.012012477900732316] +} +``` + +where the `length` value is in units of seconds. + +Do note that this dictionary might not be complete or could be empty as it depends on the target backend reporting gate lengths on every gate for each qubit. + +This defaults to False + + + +### supports\_natural\_direction + +Return whether the plugin supports a toggle for considering directionality of 2-qubit gates as `natural_direction`. + +Refer to the documentation for [`UnitarySynthesis`](qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") for the possible values and meaning of these values. + + + +### supports\_pulse\_optimize + +Return whether the plugin supports a toggle to optimize pulses during synthesis as `pulse_optimize`. + +Refer to the documentation for [`UnitarySynthesis`](qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") for the possible values and meaning of these values. + + + +### supports\_target + +Whether the plugin supports taking `target` as an option + +`target` will be a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the target device for the output of the synthesis pass. + +By default this will be `False` since the plugin interface predates the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class. If a plugin returns `True` for this attribute, it is expected that the plugin will use the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") instead of the values passed if any of `supports_gate_lengths`, `supports_gate_errors`, `supports_coupling_map`, and `supports_basis_gates` are set (although ideally all those parameters should contain duplicate information). + +## Methods + +### run + + + +`abstract run(unitary, **options)` + +Run synthesis for the given unitary matrix + +**Parameters** + +* **unitary** ([*numpy.ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – The unitary matrix to synthesize to a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object +* **options** – The optional kwargs that are passed based on the output the `support_*` methods on the class. Refer to the documentation for these methods on [`UnitarySynthesisPlugin`](#qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") to see what the keys and values are. + +**Returns** + +The dag circuit representation of the unitary. Alternatively, you can return a tuple of the form `(dag, wires)` where `dag` is the dag circuit representation of the circuit representation of the unitary and `wires` is the mapping wires to use for [`qiskit.dagcircuit.DAGCircuit.substitute_node_with_dag()`](qiskit.dagcircuit.DAGCircuit#substitute_node_with_dag "qiskit.dagcircuit.DAGCircuit.substitute_node_with_dag"). If you return a tuple and `wires` is `None` this will behave just as if only a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") was returned. Additionally if this returns `None` no substitution will be made. + +**Return type** + +[DAGCircuit](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md new file mode 100644 index 00000000000..08ab5da53cd --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager.md @@ -0,0 +1,20 @@ +--- +title: UnitarySynthesisPluginManager +description: API reference for qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager +--- + +# UnitarySynthesisPluginManager + + + +`qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/plugin.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Unitary Synthesis plugin manager class + +This class tracks the installed plugins, it has a single property, `ext_plugins` which contains a list of stevedore plugin objects. + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md new file mode 100644 index 00000000000..e271476482c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names.md @@ -0,0 +1,26 @@ +--- +title: unitary_synthesis_plugin_names +description: API reference for qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names +--- + + + +# qiskit.transpiler.passes.synthesis.plugin.unitary\_synthesis\_plugin\_names + + + +`qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/passes/synthesis/plugin.py "view source code") + +Return a list of installed unitary synthesis plugin names + +**Returns** + +A list of the installed unitary synthesis plugin names. The plugin names are valid values for the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") kwarg `unitary_synthesis_method`. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md b/docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md new file mode 100644 index 00000000000..f8f64d28ba1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.md @@ -0,0 +1,39 @@ +--- +title: PassManagerStagePlugin +description: API reference for qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin +--- + +# PassManagerStagePlugin + + + +`qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") + +Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC "(in Python v3.12)") + +A `PassManagerStagePlugin` is a plugin interface object for using custom stages in [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"). + +A `PassManagerStagePlugin` object can be added to an external package and integrated into the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function with an entry point. This will enable users to use the output of [`pass_manager()`](#qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.pass_manager "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin.pass_manager") to implement a stage in the compilation process. + +## Methods + +### pass\_manager + + + +`abstract pass_manager(pass_manager_config, optimization_level=None)` + +This method is designed to return a [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") for the stage this implements + +**Parameters** + +* **pass\_manager\_config** ([*PassManagerConfig*](qiskit.transpiler.PassManagerConfig "qiskit.transpiler.passmanager_config.PassManagerConfig")) – A configuration object that defines all the target device specifications and any user specified options to [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`generate_preset_pass_manager()`](transpiler_preset#qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager "qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager") +* **optimization\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The optimization level of the transpilation, if set this should be used to set values for any tunable parameters to trade off runtime for potential optimization. Valid values should be `0`, `1`, `2`, or `3` and the higher the number the more optimization is expected. + +**Return type** + +[*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.passmanager.PassManager") + diff --git a/docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md b/docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md new file mode 100644 index 00000000000..3f9d49eb406 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager.md @@ -0,0 +1,32 @@ +--- +title: PassManagerStagePluginManager +description: API reference for qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager +--- + +# PassManagerStagePluginManager + + + +`qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Manager class for preset pass manager stage plugins. + +## Methods + +### get\_passmanager\_stage + + + +`get_passmanager_stage(stage_name, plugin_name, pm_config, optimization_level=None)` + +Get a stage + +**Return type** + +[*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.passmanager.PassManager") + diff --git a/docs/api/qiskit/0.46/qiskit.utils.QuantumInstance.md b/docs/api/qiskit/0.46/qiskit.utils.QuantumInstance.md new file mode 100644 index 00000000000..d57cf46fdc7 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.utils.QuantumInstance.md @@ -0,0 +1,316 @@ +--- +title: QuantumInstance +description: API reference for qiskit.utils.QuantumInstance +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.utils.QuantumInstance +--- + +# QuantumInstance + + + +`qiskit.utils.QuantumInstance(backend, shots=None, seed_simulator=None, basis_gates=None, coupling_map=None, initial_layout=None, pass_manager=None, bound_pass_manager=None, seed_transpiler=None, optimization_level=None, backend_options=None, noise_model=None, timeout=None, wait=5.0, skip_qobj_validation=True, measurement_error_mitigation_cls=None, cals_matrix_refresh_period=30, measurement_error_mitigation_shots=None, job_callback=None, mit_pattern=None, max_job_retries=50)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/quantum_instance.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: Quantum Backend including execution setting. + +Quantum Instance holds a Qiskit Terra backend as well as configuration for circuit transpilation and execution. When provided to an Aqua algorithm the algorithm will execute the circuits it needs to run using the instance. + + + The class `qiskit.utils.quantum_instance.QuantumInstance` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/qi\_migration](https://qisk.it/qi_migration). + + +**Parameters** + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – Instance of selected backend +* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Number of repetitions of each circuit, for sampling. If None, the shots are extracted from the backend. If the backend has none set, the default is 1024. +* **seed\_simulator** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Random seed for simulators +* **basis\_gates** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] | None*) – List of basis gate names supported by the target. Defaults to basis gates of the backend. +* **coupling\_map** (*Optional\[Union\['CouplingMap', List\[List]]]*) – Coupling map (perhaps custom) to target in mapping +* **initial\_layout** (*Optional\[Union\['Layout', Dict, List]]*) – Initial layout of qubits in mapping +* **pass\_manager** (*Optional\['PassManager']*) – Pass manager to handle how to compile the circuits. To run only this pass manager and not the `bound_pass_manager`, call the [`transpile()`](#qiskit.utils.QuantumInstance.transpile "qiskit.utils.QuantumInstance.transpile") method with the argument `pass_manager=quantum_instance.unbound_pass_manager`. +* **bound\_pass\_manager** (*Optional\['PassManager']*) – A second pass manager to apply on bound circuits only, that is, circuits without any free parameters. To only run this pass manager and not `pass_manager` call the [`transpile()`](#qiskit.utils.QuantumInstance.transpile "qiskit.utils.QuantumInstance.transpile") method with the argument `pass_manager=quantum_instance.bound_pass_manager`. manager should also be run. +* **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The random seed for circuit mapper +* **optimization\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time. +* **backend\_options** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)") *| None*) – All running options for backend, please refer to the provider of the backend for information as to what options it supports. +* **noise\_model** (*Optional\['NoiseModel']*) – noise model for simulator +* **timeout** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – Seconds to wait for job. If None, wait indefinitely. +* **wait** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Seconds between queries for job result +* **skip\_qobj\_validation** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Bypass Qobj validation to decrease circuit processing time during submission to backend. +* **measurement\_error\_mitigation\_cls** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – The approach to mitigate measurement errors. The classes [`CompleteMeasFitter`](qiskit.utils.mitigation.CompleteMeasFitter "qiskit.utils.mitigation.CompleteMeasFitter") or [`TensoredMeasFitter`](qiskit.utils.mitigation.TensoredMeasFitter "qiskit.utils.mitigation.TensoredMeasFitter") from the [`qiskit.utils.mitigation`](utils_mitigation#module-qiskit.utils.mitigation "qiskit.utils.mitigation") module can be used here as exact values, not instances. `TensoredMeasFitter` doesn’t support the `subset_fitter` method. +* **cals\_matrix\_refresh\_period** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – How often to refresh the calibration matrix in measurement mitigation. in minutes +* **measurement\_error\_mitigation\_shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – The number of shots number for building calibration matrix. If None, the main shots parameter value is used. +* **job\_callback** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – Optional user supplied callback which can be used to monitor job progress as jobs are submitted for processing by an Aqua algorithm. The callback is provided the following arguments: job\_id, job\_status, queue\_position, job +* **mit\_pattern** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – Qubits on which to perform the TensoredMeasFitter measurement correction, divided to groups according to tensors. If None and qr is given then assumed to be performed over the entire qr as one group (default None). +* **max\_job\_retries** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – positive non-zero number of trials for the job set (-1 for infinite trials) (default: 50) + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – the shots exceeds the maximum number of shots +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – set noise model but the backend does not support that +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – set backend\_options but the backend does not support that + +## Attributes + + + +### backend + +Return Backend backend object. + + + +### backend\_config + +Getter of backend\_config. + + + +### backend\_name + +Return backend name. + + + +### backend\_options + +Getter of backend\_options. + + + +### bound\_pass\_manager + +Return the pass manager for designated for bound circuits. + +**Returns** + +The pass manager for bound circuits, if it has been set. + +**Return type** + +Optional\[‘PassManager’] + + + +### cals\_matrix\_refresh\_period + +returns matrix refresh period + + + +### circuit\_summary + +Getter of circuit summary. + + + +### compile\_config + +Getter of compile\_config. + + + +### is\_local + +Return True if backend is a local backend. + + + +### is\_simulator + +Return True if backend is a simulator. + + + +### is\_statevector + +Return True if backend is a statevector-type simulator. + + + +### max\_job\_retries + +Getter of max tries + + + +### measurement\_error\_mitigation\_cls + +returns measurement error mitigation cls + + + +### measurement\_error\_mitigation\_shots + +returns measurement error mitigation shots + + + +### noise\_config + +Getter of noise\_config. + + + +### qjob\_config + +Getter of qjob\_config. + + + +### run\_config + +Getter of run\_config. + + + +### skip\_qobj\_validation + +checks if skip qobj validation + + + +### time\_taken + +Accumulated time taken for execution. + + + +### unbound\_pass\_manager + +Return the pass manager for designated for unbound circuits. + +**Returns** + +The pass manager for unbound circuits, if it has been set. + +**Return type** + +Optional\[‘PassManager’] + +## Methods + +### assemble + + + +`assemble(circuits)` + +assemble circuits + +**Return type** + +[*QasmQobj*](qiskit.qobj.QasmQobj "qiskit.qobj.qasm_qobj.QasmQobj") | [*PulseQobj*](qiskit.qobj.PulseQobj "qiskit.qobj.pulse_qobj.PulseQobj") + +### cals\_matrix + + + +`cals_matrix(qubit_index=None)` + +Get the stored calibration matrices and its timestamp. + +**Parameters** + +**qubit\_index** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – the qubit index of corresponding calibration matrix. If None, return all stored calibration matrices. + +**Returns** + +The calibration matrix and the creation timestamp if qubit\_index is not None otherwise, return all matrices and their timestamp in a dictionary. + +**Return type** + +[*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")] | [*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]] | None + +### execute + + + +`execute(circuits, had_transpiled=False)` + +A wrapper to interface with quantum backend. + +**Parameters** + +* **circuits** (*Union\['QuantumCircuit', List\['QuantumCircuit']]*) – circuits to execute +* **had\_transpiled** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether or not circuits had been transpiled + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Invalid error mitigation fitter class +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – TensoredMeasFitter class doesn’t support subset fitter +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Ignis not installed + +**Returns** + +result object + +**Return type** + +[Result](qiskit.result.Result "qiskit.result.Result") + +**TODO: Maybe we can combine the circuits for the main ones and calibration circuits before** + +assembling to the qobj. + +### maybe\_refresh\_cals\_matrix + + + +`maybe_refresh_cals_matrix(timestamp=None)` + +Calculate the time difference from the query of last time. + +**Parameters** + +**timestamp** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *| None*) – timestamp + +**Returns** + +Whether or not refresh the cals\_matrix + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### reset\_execution\_results + + + +`reset_execution_results()` + +Reset execution results + +### set\_config + + + +`set_config(**kwargs)` + +Set configurations for the quantum instance. + +### transpile + + + +`transpile(circuits, pass_manager=None)` + +A wrapper to transpile circuits to allow algorithm access the transpiled circuits. + +**Parameters** + +* **circuits** (*Union\['QuantumCircuit', List\['QuantumCircuit']]*) – circuits to transpile +* **pass\_manager** (*Optional\['PassManager']*) – A pass manager to transpile the circuits. If none is given, but either `pass_manager` or `bound_pass_manager` has been set in the initializer, these are run. If none has been provided there either, the backend and compile configs from the initializer are used. + +**Returns** + +**The transpiled circuits, it is always a list even though** + +the length is one. + +**Return type** + +List\[‘QuantumCircuit’] + diff --git a/docs/api/qiskit/0.46/qiskit.utils.mitigation.CompleteMeasFitter.md b/docs/api/qiskit/0.46/qiskit.utils.mitigation.CompleteMeasFitter.md new file mode 100644 index 00000000000..7a71cec3797 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.utils.mitigation.CompleteMeasFitter.md @@ -0,0 +1,128 @@ +--- +title: CompleteMeasFitter +description: API reference for qiskit.utils.mitigation.CompleteMeasFitter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.utils.mitigation.CompleteMeasFitter +--- + +# CompleteMeasFitter + + + +`qiskit.utils.mitigation.CompleteMeasFitter(results, state_labels, qubit_list=None, circlabel='')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/mitigation/fitters.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: Measurement correction fitter for a full calibration + +Initialize a measurement calibration matrix from the results of running the circuits returned by measurement\_calibration\_circuits + +A wrapper for the tensored fitter + + + This class is not a public API. The internals are not stable and will likely change. It is used solely for the `measurement_error_mitigation_cls` kwarg of the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") class’s constructor (as a class not an instance). Anything outside of that usage does not have the normal user-facing API stability. + + + + The class `qiskit.utils.mitigation.fitters.CompleteMeasFitter` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/qi\_migration](https://qisk.it/qi_migration). + + +**Parameters** + +* **results** – the results of running the measurement calibration circuits. If this is None the user will set a calibration matrix later. +* **state\_labels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – list of calibration state labels returned from measurement\_calibration\_circuits. The output matrix will obey this ordering. +* **qubit\_list** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]*) – List of the qubits (for reference and if the subset is needed). If None, the qubit\_list will be created according to the length of state\_labels\[0]. +* **circlabel** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – if the qubits were labeled. + +## Attributes + + + +### cal\_matrix + +Return cal\_matrix. + + + +### filter + +Return a measurement filter using the cal matrix. + + + +### qubit\_list + +Return list of qubits. + + + +### state\_labels + +Return state\_labels. + +## Methods + +### add\_data + + + +`add_data(new_results, rebuild_cal_matrix=True)` + +Add measurement calibration data + +**Parameters** + +* **new\_results** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*qiskit.result.Result*](qiskit.result.Result "qiskit.result.Result")) – a single result or list of result objects. +* **rebuild\_cal\_matrix** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – rebuild the calibration matrix + +### readout\_fidelity + + + +`readout_fidelity(label_list=None)` + +Based on the results, output the readout fidelity which is the normalized trace of the calibration matrix + +**Parameters** + +**label\_list** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If None, returns the average assignment fidelity of a single state. Otherwise it returns the assignment fidelity to be in any one of these states averaged over the second index. + +**Returns** + +readout fidelity (assignment fidelity) + +**Return type** + +numpy.array + +**Additional Information:** + +The on-diagonal elements of the calibration matrix are the probabilities of measuring state ‘x’ given preparation of state ‘x’ and so the normalized trace is the average assignment fidelity + +### subset\_fitter + + + +`subset_fitter(qubit_sublist)` + +Return a fitter object that is a subset of the qubits in the original list. + +**Parameters** + +**qubit\_sublist** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – must be a subset of qubit\_list + +**Returns** + +**A new fitter that has the calibration for a** + +subset of qubits + +**Return type** + +[CompleteMeasFitter](#qiskit.utils.mitigation.CompleteMeasFitter "qiskit.utils.mitigation.CompleteMeasFitter") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the calibration matrix is not initialized + diff --git a/docs/api/qiskit/0.46/qiskit.utils.mitigation.TensoredMeasFitter.md b/docs/api/qiskit/0.46/qiskit.utils.mitigation.TensoredMeasFitter.md new file mode 100644 index 00000000000..0c48b247637 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.utils.mitigation.TensoredMeasFitter.md @@ -0,0 +1,139 @@ +--- +title: TensoredMeasFitter +description: API reference for qiskit.utils.mitigation.TensoredMeasFitter +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.utils.mitigation.TensoredMeasFitter +--- + +# TensoredMeasFitter + + + +`qiskit.utils.mitigation.TensoredMeasFitter(results, mit_pattern, substate_labels_list=None, circlabel='')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/mitigation/fitters.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Deprecated: Measurement correction fitter for a tensored calibration. + +Initialize a measurement calibration matrix from the results of running the circuits returned by measurement\_calibration\_circuits. + + + This class is not a public API. The internals are not stable and will likely change. It is used solely for the `measurement_error_mitigation_cls` kwarg of the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") class’s constructor (as a class not an instance). Anything outside of that usage does not have the normal user-facing API stability. + + + + The class `qiskit.utils.mitigation.fitters.TensoredMeasFitter` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/qi\_migration](https://qisk.it/qi_migration). + + +**Parameters** + +* **results** – the results of running the measurement calibration circuits. If this is None, the user will set calibration matrices later. +* **mit\_pattern** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – qubits to perform the measurement correction on, divided to groups according to tensors +* **substate\_labels\_list** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]]*) – for each calibration matrix, the labels of its rows and columns. If None, the labels are ordered lexicographically +* **circlabel** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – if the qubits were labeled + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if the mit\_pattern doesn’t match the substate\_labels\_list + +## Attributes + + + +### cal\_matrices + +Return cal\_matrices. + + + +### filter + +Return a measurement filter using the cal matrices. + + + +### nqubits + +Return \_qubit\_list\_sizes. + + + +### substate\_labels\_list + +Return \_substate\_labels\_list. + +## Methods + +### add\_data + + + +`add_data(new_results, rebuild_cal_matrix=True)` + +Add measurement calibration data + +**Parameters** + +* **new\_results** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*qiskit.result.Result*](qiskit.result.Result "qiskit.result.Result")) – a single result or list of Result objects. +* **rebuild\_cal\_matrix** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – rebuild the calibration matrix + +### readout\_fidelity + + + +`readout_fidelity(cal_index=0, label_list=None)` + +Based on the results, output the readout fidelity, which is the average of the diagonal entries in the calibration matrices. + +**Parameters** + +* **cal\_index** (*integer*) – readout fidelity for this index in \_cal\_matrices +* **label\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Returns the average fidelity over of the groups f states. In the form of a list of lists of states. If None, then each state used in the construction of the calibration matrices forms a group of size 1 + +**Returns** + +The readout fidelity (assignment fidelity) + +**Return type** + +numpy.array + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the calibration matrix has not been set for the object. + +**Additional Information:** + +The on-diagonal elements of the calibration matrices are the probabilities of measuring state ‘x’ given preparation of state ‘x’. + +### subset\_fitter + + + +`subset_fitter(qubit_sublist)` + +Return a fitter object that is a subset of the qubits in the original list. + +This is only a partial implementation of the `subset_fitter` method since only mitigation patterns of length 1 are supported. This corresponds to patterns of the form `[[0], [1], [2], ...]`. Note however, that such patterns are a good first approximation to mitigate readout errors on large quantum circuits. + +**Parameters** + +**qubit\_sublist** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – must be a subset of qubit\_list + +**Returns** + +**A new fitter that has the calibration for a** + +subset of qubits + +**Return type** + +[TensoredMeasFitter](#qiskit.utils.mitigation.TensoredMeasFitter "qiskit.utils.mitigation.TensoredMeasFitter") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the calibration matrix is not initialized +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If the mit pattern is not a tensor of single-qubit measurement error mitigation. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If a qubit in the given `qubit_sublist` is not in the list of qubits in the mit. pattern. + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.array_to_latex.md b/docs/api/qiskit/0.46/qiskit.visualization.array_to_latex.md new file mode 100644 index 00000000000..6846804a895 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.array_to_latex.md @@ -0,0 +1,51 @@ +--- +title: array_to_latex +description: API reference for qiskit.visualization.array_to_latex +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.array_to_latex +--- + + + +# qiskit.visualization.array\_to\_latex + + + +`qiskit.visualization.array_to_latex(array, precision=10, prefix='', source=False, max_size=8)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/array.py "view source code") + +Latex representation of a complex numpy array (with dimension 1 or 2) + +**Parameters** + +* **array** (*ndarray*) – The array to be converted to latex, must have dimension 1 or 2 and contain only numerical data. + +* **precision** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – For numbers not close to integers or common terms, the number of decimal places to round to. + +* **prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Latex string to be prepended to the latex, intended for labels. + +* **source** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `False`, will return IPython.display.Latex object. If display is `True`, will instead return the LaTeX source string. + +* **max\_size** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*(*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*) or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – + + The maximum size of the output Latex array. + + * If list(`int`), then the 0th element of the list specifies the maximum width (including dots characters) and the 1st specifies the maximum height (also inc. dots characters). + * If a single `int` then this value sets the maximum width \_and\_ maximum height. + +**Returns** + +**If `source` is `True`, a `str` of the LaTeX** + +representation of the array, else an `IPython.display.Latex` representation of the array. + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") or IPython.display.Latex + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – If array can not be interpreted as a numerical numpy array. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the dimension of array is not 1 or 2. +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – If `source` is `False` and `IPython.display.Latex` cannot be imported. + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.circuit.qcstyle.DefaultStyle.md b/docs/api/qiskit/0.46/qiskit.visualization.circuit.qcstyle.DefaultStyle.md new file mode 100644 index 00000000000..646f7fcbc40 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.circuit.qcstyle.DefaultStyle.md @@ -0,0 +1,161 @@ +--- +title: DefaultStyle +description: API reference for qiskit.visualization.circuit.qcstyle.DefaultStyle +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.visualization.circuit.qcstyle.DefaultStyle +--- + +# DefaultStyle + + + +`qiskit.visualization.circuit.qcstyle.DefaultStyle`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/circuit/qcstyle.py "view source code") + +Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)") + +Creates a Default Style dictionary + +**Style Dict Details** + +The style dict contains numerous options that define the style of the output circuit visualization. The style dict is used by the mpl or latex output. The options available in the style dict are defined below: + +**name (str): the name of the style. The name can be set to `iqp`,** + +`iqp-dark`, `textbook`, `bw`, `clifford`, or the name of a user-created json file. This overrides the setting in the user config file (usually `~/.qiskit/settings.conf`). + +**textcolor (str): the color code to use for all text not inside a gate.** + +Defaults to `#000000` + +**subtextcolor (str): the color code to use for subtext. Defaults to** + +`#000000` + +**linecolor (str): the color code to use for lines. Defaults to** + +`#000000` + +**creglinecolor (str): the color code to use for classical register** + +lines. Defaults to `#778899` + +**gatetextcolor (str): the color code to use for gate text. Defaults to** + +`#000000` + +**gatefacecolor (str): the color code to use for a gate if no color** + +specified in the ‘displaycolor’ dict. Defaults to `#BB8BFF` + +**barrierfacecolor (str): the color code to use for barriers. Defaults to** + +`#BDBDBD` + +**backgroundcolor (str): the color code to use for the background.** + +Defaults to `#FFFFFF` + +**edgecolor (str): the color code to use for gate edges when using the** + +bw style. Defaults to `#000000`. + +fontsize (int): the font size to use for text. Defaults to 13. + +subfontsize (int): the font size to use for subtext. Defaults to 8. + +**showindex (bool): if set to True, show the index numbers at the top.** + +Defaults to False. + +**figwidth (int): the maximum width (in inches) for the output figure.** + +If set to -1, the maximum displayable width will be used. Defaults to -1. + +dpi (int): the DPI to use for the output image. Defaults to 150. + +**margin (list): a list of margin values to adjust spacing around output** + +image. Takes a list of 4 ints: \[x left, x right, y bottom, y top]. Defaults to \[2.0, 0.1, 0.1, 0.3]. + +**creglinestyle (str): The style of line to use for classical registers.** + +Choices are `solid`, `doublet`, or any valid matplotlib linestyle kwarg value. Defaults to `doublet`. + +**displaytext (dict): a dictionary of the text to use for certain element** + +types in the output visualization. These items allow the use of LaTeX formatting for gate names. The ‘displaytext’ dict can contain any number of elements. User created names and labels may be used as keys, which allow these to have Latex formatting. The default values are (default.json): + +```python +{ + 'u1': 'U_1', + 'u2': 'U_2', + 'u3': 'U_3', + 'sdg': 'S^\dagger', + 'sx': '\sqrt{X}', + 'sxdg': '\sqrt{X}^\dagger', + 't': 'T', + 'tdg': 'T^\dagger', + 'dcx': 'Dcx', + 'iswap': 'Iswap', + 'ms': 'MS', + 'rx': 'R_X', + 'ry': 'R_Y', + 'rz': 'R_Z', + 'rxx': 'R_{XX}', + 'ryy': 'R_{YY}', + 'rzx': 'R_{ZX}', + 'rzz': 'ZZ', + 'reset': '\left|0\right\rangle', + 'initialize': '|\psi\rangle' +} +``` + +**displaycolor (dict): the color codes to use for each circuit element in** + +the form (gate\_color, text\_color). Colors can also be entered without the text color, such as ‘u1’: ‘#FA74A6’, in which case the text color will always be gatetextcolor. The displaycolor dict can contain any number of elements. User names and labels may be used as keys, which allows for custom colors for user-created gates. The default values are (default.json): + +```python +{ + 'u1': ('#FA74A6', '#000000'), + 'u2': ('#FA74A6', '#000000'), + 'u3': ('#FA74A6', '#000000'), + 'id': ('#05BAB6', '#000000'), + 'u': ('#BB8BFF', '#000000'), + 'p': ('#BB8BFF', '#000000'), + 'x': ('#05BAB6', '#000000'), + 'y': ('#05BAB6', '#000000'), + 'z': ('#05BAB6', '#000000'), + 'h': ('#6FA4FF', '#000000'), + 'cx': ('#6FA4FF', '#000000'), + 'ccx': ('#BB8BFF', '#000000'), + 'mcx': ('#BB8BFF', '#000000'), + 'mcx_gray': ('#BB8BFF', '#000000'), + 'cy': ('#6FA4FF', '#000000'), + 'cz': ('#6FA4FF', '#000000'), + 'swap': ('#6FA4FF', '#000000'), + 'cswap': ('#BB8BFF', '#000000'), + 'ccswap': ('#BB8BFF', '#000000'), + 'dcx': ('#6FA4FF', '#000000'), + 'cdcx': ('#BB8BFF', '#000000'), + 'ccdcx': ('#BB8BFF', '#000000'), + 'iswap': ('#6FA4FF', '#000000'), + 's': ('#6FA4FF', '#000000'), + 'sdg': ('#6FA4FF', '#000000'), + 't': ('#BB8BFF', '#000000'), + 'tdg': ('#BB8BFF', '#000000'), + 'sx': ('#6FA4FF', '#000000'), + 'sxdg': ('#6FA4FF', '#000000') + 'r': ('#BB8BFF', '#000000'), + 'rx': ('#BB8BFF', '#000000'), + 'ry': ('#BB8BFF', '#000000'), + 'rz': ('#BB8BFF', '#000000'), + 'rxx': ('#BB8BFF', '#000000'), + 'ryy': ('#BB8BFF', '#000000'), + 'rzx': ('#BB8BFF', '#000000'), + 'reset': ('#000000', '#FFFFFF'), + 'target': ('#FFFFFF', '#FFFFFF'), + 'measure': ('#000000', '#FFFFFF'), +} +``` + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.circuit_drawer.md b/docs/api/qiskit/0.46/qiskit.visualization.circuit_drawer.md new file mode 100644 index 00000000000..5a089c3f88b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.circuit_drawer.md @@ -0,0 +1,91 @@ +--- +title: circuit_drawer +description: API reference for qiskit.visualization.circuit_drawer +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.circuit_drawer +--- + + + +# qiskit.visualization.circuit\_drawer + + + +`qiskit.visualization.circuit_drawer(circuit, scale=None, filename=None, style=None, output=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=True, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/circuit/circuit_visualization.py "view source code") + +Draw the quantum circuit. Use the output parameter to choose the drawing format: + +**text**: ASCII art TextDrawing that can be printed in the console. + +**matplotlib**: images with color rendered purely in Python. + +**latex**: high-quality images compiled via latex. + +**latex\_source**: raw uncompiled latex output. + + + Support for [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") nodes in conditions and `SwitchCaseOp.target` fields is preliminary and incomplete. The `text` and `mpl` drawers will make a best-effort attempt to show data dependencies, but the LaTeX-based drawers will skip these completely. + + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – the quantum circuit to draw +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – scale of image to draw (shrink if \< 1.0). Only used by the mpl, latex and latex\_source outputs. Defaults to 1.0. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. Defaults to None. +* **style** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – dictionary of style or file name of style json file. This option is only used by the mpl or latex output type. If style is a str, it is used as the path to a json file which contains a style dict. The file will be opened, parsed, and then any style elements in the dict will replace the default values in the input dict. A file to be loaded must end in `.json`, but the name entered here can omit `.json`. For example, `style='iqp.json'` or `style='iqp'`. If style is a dict and the `'name'` key is set, that name will be used to load a json file, followed by loading the other items in the style dict. For example, `style={'name': 'iqp'}`. If style is not a str and name is not a key in the style dict, then the default value from the user config file (usually `~/.qiskit/settings.conf`) will be used, for example, `circuit_mpl_style = iqp`. If none of these are set, the clifford style will be used. The search path for style json files can be specified in the user config, for example, `circuit_mpl_style_path = /home/user/styles:/home/user`. See: [`DefaultStyle`](qiskit.visualization.circuit.qcstyle.DefaultStyle "qiskit.visualization.circuit.qcstyle.DefaultStyle") for more information on the contents. +* **output** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – select the output method to use for drawing the circuit. Valid choices are `text`, `mpl`, `latex`, `latex_source`. By default, the text drawer is used unless the user config file (usually `~/.qiskit/settings.conf`) has an alternative backend set as the default. For example, `circuit_drawer = latex`. If the output kwarg is set, that backend will always be used over the default in the user config file. +* **interactive** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – when set to true, show the circuit in a new window (for mpl this depends on the matplotlib backend being used supporting this). Note when used with either the text or the latex\_source output type this has no effect and will be silently ignored. Defaults to False. +* **reverse\_bits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – when set to True, reverse the bit order inside registers for the output visualization. Defaults to False unless the user config file (usually `~/.qiskit/settings.conf`) has an alternative value set. For example, `circuit_reverse_bits = True`. +* **plot\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – enable/disable drawing barriers in the output circuit. Defaults to True. +* **justify** (*string*) – options are `left`, `right` or `none`. If anything else is supplied, it defaults to left justified. It refers to where gates should be placed in the output circuit if there is an option. `none` results in each gate being placed in its own column. +* **vertical\_compression** (*string*) – `high`, `medium` or `low`. It merges the lines generated by the text output so the drawing will take less vertical room. Default is `medium`. Only used by the text output, will be silently ignored otherwise. +* **idle\_wires** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – include idle wires (wires with no circuit elements) in output visualization. Default is True. +* **with\_layout** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – include layout information, with labels on the physical layout. Default is True. +* **fold** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – sets pagination. It can be disabled using -1. In text, sets the length of the lines. This is useful when the drawing does not fit in the console. If None (default), it will try to guess the console width using `shutil.get_terminal_size()`. However, if running in jupyter, the default line length is set to 80 characters. In mpl, it is the number of (visual) layers before folding. Default is 25. +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – Only used by the mpl backend. An optional Axes object to be used for the visualization output. If none is specified, a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. +* **initial\_state** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional. Adds `|0>` in the beginning of the wire. Default is False. +* **cregbundle** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional. If set True, bundle classical registers into a single wire. Default is true if possible, and false if a block instruction needs to access an individual bit from a register. +* **wire\_order** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Optional. A list of integers used to reorder the display of the bits. The list must have an entry for every bit with the bits in the range 0 to (num\_qubits + num\_clbits). +* **expr\_len** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The number of characters to display if an [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") is used for the condition in a [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp"). If this number is exceeded, the string will be truncated at that number and ‘…’ added to the end. + +**Returns** + +`TextDrawing` or `matplotlib.figure` or `PIL.Image` or [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"): + +* **TextDrawing (output=’text’)** + + A drawing that can be printed as ascii art. + +* **matplotlib.figure.Figure (output=’mpl’)** + + A matplotlib figure object for the circuit diagram. + +* **PIL.Image (output=’latex’)** + + An in-memory representation of the image of the circuit diagram. + +* **str (output=’latex\_source’)** + + The LaTeX source code for visualizing the circuit diagram. + +**Raises** + +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – when an invalid output method is selected +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – when the output methods requires non-installed libraries. + +**Example** + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.tools.visualization import circuit_drawer +q = QuantumRegister(1) +c = ClassicalRegister(1) +qc = QuantumCircuit(q, c) +qc.h(q) +qc.measure(q, c) +circuit_drawer(qc, output='mpl', style={'backgroundcolor': '#EEEEEE'}) +``` + +![../\_images/qiskit-visualization-circuit\_drawer-1.png](/images/api/qiskit/0.46/qiskit-visualization-circuit_drawer-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.dag_drawer.md b/docs/api/qiskit/0.46/qiskit.visualization.dag_drawer.md new file mode 100644 index 00000000000..e715833e0f2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.dag_drawer.md @@ -0,0 +1,62 @@ +--- +title: dag_drawer +description: API reference for qiskit.visualization.dag_drawer +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.dag_drawer +--- + + + +# qiskit.visualization.dag\_drawer + + + +`qiskit.visualization.dag_drawer(dag, scale=0.7, filename=None, style='color')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/dag_visualization.py "view source code") + +Plot the directed acyclic graph (dag) to represent operation dependencies in a quantum circuit. + +This function calls the [`graphviz_draw()`](https://www.rustworkx.org/apiref/rustworkx.visualization.graphviz_draw.html#rustworkx.visualization.graphviz_draw "(in rustworkx v0.14.0)") function from the `rustworkx` package to draw the DAG. + +**Parameters** + +* **dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – The dag to draw. +* **scale** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – scaling factor +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to (format inferred from name) +* **style** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – ‘plain’: B\&W graph ‘color’ (default): color input/output/op nodes + +**Returns** + +**if in Jupyter notebook and not saving to file,** + +otherwise None. + +**Return type** + +PIL.Image + +**Raises** + +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – when style is not recognized. +* [**InvalidFileError**](exceptions#qiskit.exceptions.InvalidFileError "qiskit.exceptions.InvalidFileError") – when filename provided is not valid + +**Example** + +```python +from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit +from qiskit.dagcircuit import DAGCircuit +from qiskit.converters import circuit_to_dag +from qiskit.visualization import dag_drawer + +q = QuantumRegister(3, 'q') +c = ClassicalRegister(3, 'c') +circ = QuantumCircuit(q, c) +circ.h(q[0]) +circ.cx(q[0], q[1]) +circ.measure(q[0], c[0]) +circ.rz(0.5, q[1]).c_if(c, 2) + +dag = circuit_to_dag(circ) +dag_drawer(dag) +``` + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.pass_manager_drawer.md b/docs/api/qiskit/0.46/qiskit.visualization.pass_manager_drawer.md new file mode 100644 index 00000000000..068c6b20607 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.pass_manager_drawer.md @@ -0,0 +1,62 @@ +--- +title: pass_manager_drawer +description: API reference for qiskit.visualization.pass_manager_drawer +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.pass_manager_drawer +--- + + + +# qiskit.visualization.pass\_manager\_drawer + + + +`qiskit.visualization.pass_manager_drawer(pass_manager, filename=None, style=None, raw=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/pass_manager_visualization.py "view source code") + +Draws the pass manager. + +This function needs [pydot](https://github.com/pydot/pydot), which in turn needs [Graphviz](https://www.graphviz.org/) to be installed. + +**Parameters** + +* **pass\_manager** ([*PassManager*](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager")) – the pass manager to be drawn +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to +* **style** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *or OrderedDict*) – keys are the pass classes and the values are the colors to make them. An example can be seen in the DEFAULT\_STYLE. An ordered dict can be used to ensure a priority coloring when pass falls into multiple categories. Any values not included in the provided dict will be filled in from the default dict +* **raw** ([*Bool*](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool")) – True if you want to save the raw Dot output not an image. The default is False. + +**Returns** + +an in-memory representation of the pass manager. Or None if no image was generated or PIL is not installed. + +**Return type** + +PIL.Image or None + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – when nxpd or pydot not installed. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – If raw=True and filename=None. + +**Example** + +```python + %matplotlib inline +from qiskit import QuantumCircuit +from qiskit.compiler import transpile +from qiskit.transpiler import PassManager +from qiskit.visualization import pass_manager_drawer +from qiskit.transpiler.passes import Unroller + +circ = QuantumCircuit(3) +circ.ccx(0, 1, 2) +circ.draw() + +pass_ = Unroller(['u1', 'u2', 'u3', 'cx']) +pm = PassManager(pass_) +new_circ = pm.run(circ) +new_circ.draw(output='mpl') + +pass_manager_drawer(pm, "passmanager.jpg") +``` + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_multivector.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_multivector.md new file mode 100644 index 00000000000..9163bb4f15b --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_multivector.md @@ -0,0 +1,85 @@ +--- +title: plot_bloch_multivector +description: API reference for qiskit.visualization.plot_bloch_multivector +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_bloch_multivector +--- + + + +# qiskit.visualization.plot\_bloch\_multivector + + + +`qiskit.visualization.plot_bloch_multivector(state, title='', figsize=None, *, reverse_bits=False, filename=None, font_size=None, title_font_size=None, title_pad=1)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/state_visualization.py "view source code") + +Plot a Bloch sphere for each qubit. + +Each component $(x,y,z)$ of the Bloch sphere labeled as ‘qubit i’ represents the expected value of the corresponding Pauli operator acting only on that qubit, that is, the expected value of $I_{N-1} \otimes\dotsb\otimes I_{i+1}\otimes P_i \otimes I_{i-1}\otimes\dotsb\otimes I_0$, where $N$ is the number of qubits, $P\in \{X,Y,Z\}$ and $I$ is the identity operator. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") *or ndarray*) – an N-qubit quantum state. +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a string that represents the plot title +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – size of each individual Bloch sphere figure, in inches. +* **reverse\_bits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, plots qubits following Qiskit’s convention \[Default:False]. +* **font\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Font size for the Bloch ball figures. +* **title\_font\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Font size for the title. +* **title\_pad** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Padding for the title (suptitle y position is y=1+title\_pad/100). + +**Returns** + +A matplotlib figure instance. + +**Return type** + +[`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure "(in Matplotlib v3.8.2)") + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Requires matplotlib. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – if input is not a valid N-qubit state. + +**Examples** + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import Statevector +from qiskit.visualization import plot_bloch_multivector + +qc = QuantumCircuit(2) +qc.h(0) +qc.x(1) + +state = Statevector(qc) +plot_bloch_multivector(state) +``` + +![../\_images/qiskit-visualization-plot\_bloch\_multivector-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_multivector-1.png) + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import Statevector +from qiskit.visualization import plot_bloch_multivector + +qc = QuantumCircuit(2) +qc.h(0) +qc.x(1) + +# You can reverse the order of the qubits. + +from qiskit.quantum_info import DensityMatrix + +qc = QuantumCircuit(2) +qc.h([0, 1]) +qc.t(1) +qc.s(0) +qc.cx(0,1) + +matrix = DensityMatrix(qc) +plot_bloch_multivector(matrix, title='My Bloch Spheres', reverse_bits=True) +``` + +![../\_images/qiskit-visualization-plot\_bloch\_multivector-2.png](/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_multivector-2.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_vector.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_vector.md new file mode 100644 index 00000000000..7de41a589f2 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_bloch_vector.md @@ -0,0 +1,62 @@ +--- +title: plot_bloch_vector +description: API reference for qiskit.visualization.plot_bloch_vector +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_bloch_vector +--- + + + +# qiskit.visualization.plot\_bloch\_vector + + + +`qiskit.visualization.plot_bloch_vector(bloch, title='', ax=None, figsize=None, coord_type='cartesian', font_size=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/state_visualization.py "view source code") + +Plot the Bloch sphere. + +Plot a Bloch sphere with the specified coordinates, that can be given in both cartesian and spherical systems. + +**Parameters** + +* **bloch** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[double]*) – array of three elements where \[\, \, \] (Cartesian) or \[\, \, \] (spherical in radians) \ is inclination angle from +z direction \ is azimuth from +x direction +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a string that represents the plot title +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An Axes to use for rendering the bloch sphere +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. Has no effect is passing `ax`. +* **coord\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a string that specifies coordinate type for bloch (Cartesian or spherical), default is Cartesian +* **font\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Font size. + +**Returns** + +A matplotlib figure instance if `ax = None`. + +**Return type** + +[`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure "(in Matplotlib v3.8.2)") + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Requires matplotlib. + +**Examples** + +```python +from qiskit.visualization import plot_bloch_vector + +plot_bloch_vector([0,1,0], title="New Bloch Sphere") +``` + +![../\_images/qiskit-visualization-plot\_bloch\_vector-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_vector-1.png) + +```python +import numpy as np +from qiskit.visualization import plot_bloch_vector + +# You can use spherical coordinates instead of cartesian. + +plot_bloch_vector([1, np.pi/2, np.pi/3], coord_type='spherical') +``` + +![../\_images/qiskit-visualization-plot\_bloch\_vector-2.png](/images/api/qiskit/0.46/qiskit-visualization-plot_bloch_vector-2.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_circuit_layout.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_circuit_layout.md new file mode 100644 index 00000000000..e9135816645 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_circuit_layout.md @@ -0,0 +1,62 @@ +--- +title: plot_circuit_layout +description: API reference for qiskit.visualization.plot_circuit_layout +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_circuit_layout +--- + + + +# qiskit.visualization.plot\_circuit\_layout + + + +`qiskit.visualization.plot_circuit_layout(circuit, backend, view='virtual', qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/gate_map.py "view source code") + +Plot the layout of a circuit transpiled for a given target backend. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Input quantum circuit. +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – Target backend. +* **view** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Layout view: either ‘virtual’ or ‘physical’. +* **qubit\_coordinates** (*Sequence*) – An optional sequence input (list or array being the most common) of 2d coordinates for each qubit. The length of the sequence must match the number of qubits on the backend. The sequence should be the planar coordinates in a 0-based square grid where each qubit is located. + +**Returns** + +A matplotlib figure showing layout. + +**Return type** + +Figure + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Invalid view type given. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – Circuit has no layout attribute. + +**Example** + +```python +import numpy as np +from qiskit import QuantumCircuit, transpile +from qiskit.providers.fake_provider import FakeVigoV2 +from qiskit.visualization import plot_circuit_layout +from qiskit.tools.monitor import job_monitor +from qiskit.providers.fake_provider import FakeVigoV2 +import matplotlib.pyplot as plt + +ghz = QuantumCircuit(3, 3) +ghz.h(0) +for idx in range(1,3): + ghz.cx(0,idx) +ghz.measure(range(3), range(3)) + +backend = FakeVigoV2() +new_circ_lv3 = transpile(ghz, backend=backend, optimization_level=3) +plot_circuit_layout(new_circ_lv3, backend) +``` + +![../\_images/qiskit-visualization-plot\_circuit\_layout-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_circuit_layout-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_coupling_map.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_coupling_map.md new file mode 100644 index 00000000000..c8aaf26be62 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_coupling_map.md @@ -0,0 +1,62 @@ +--- +title: plot_coupling_map +description: API reference for qiskit.visualization.plot_coupling_map +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_coupling_map +--- + + + +# qiskit.visualization.plot\_coupling\_map + + + +`qiskit.visualization.plot_coupling_map(num_qubits, qubit_coordinates, coupling_map, figsize=None, plot_directed=False, label_qubits=True, qubit_size=None, line_width=4, font_size=None, qubit_color=None, qubit_labels=None, line_color=None, font_color='white', ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/gate_map.py "view source code") + +Plots an arbitrary coupling map of qubits (embedded in a plane). + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of qubits defined and plotted. +* **qubit\_coordinates** (*List\[List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – A list of two-element lists, with entries of each nested list being the planar coordinates in a 0-based square grid where each qubit is located. +* **coupling\_map** (*List\[List\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – A list of two-element lists, with entries of each nested list being the qubit numbers of the bonds to be plotted. +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Output figure size (wxh) in inches. +* **plot\_directed** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot directed coupling map. +* **label\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label the qubits. +* **qubit\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Size of qubit marker. +* **line\_width** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width of lines. +* **font\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Font size of qubit labels. +* **qubit\_color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of colors for the qubits +* **qubit\_labels** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of qubit labels +* **line\_color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of colors for each line from coupling\_map. +* **font\_color** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The font color for the qubit labels. +* **ax** (*Axes*) – A Matplotlib axes instance. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. + +**Returns** + +A Matplotlib figure instance. + +**Return type** + +Figure + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – If matplotlib or graphviz is not installed. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If length of qubit labels does not match number of qubits. + +**Example** + +```python +from qiskit.visualization import plot_coupling_map + +num_qubits = 8 +qubit_coordinates = [[0, 1], [1, 1], [1, 0], [1, 2], [2, 0], [2, 2], [2, 1], [3, 1]] +coupling_map = [[0, 1], [1, 2], [2, 3], [3, 5], [4, 5], [5, 6], [2, 4], [6, 7]] +plot_coupling_map(num_qubits, qubit_coordinates, coupling_map) +``` + +![../\_images/qiskit-visualization-plot\_coupling\_map-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_coupling_map-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_distribution.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_distribution.md new file mode 100644 index 00000000000..0a1031aeba0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_distribution.md @@ -0,0 +1,79 @@ +--- +title: plot_distribution +description: API reference for qiskit.visualization.plot_distribution +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_distribution +--- + + + +# qiskit.visualization.plot\_distribution + + + +`qiskit.visualization.plot_distribution(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/counts_visualization.py "view source code") + +Plot a distribution from input sampled data. + +**Parameters** + +* **data** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – This is either a list of dictionaries or a single dict containing the values to represent (ex \{‘001’: 130}) +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – String or list of strings for distribution bar colors. +* **number\_to\_keep** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of terms to plot per dataset. The rest is made into a single bar called ‘rest’. If multiple datasets are given, the `number_to_keep` applies to each dataset individually, which may result in more bars than `number_to_keep + 1`. The `number_to_keep` applies to the total values, rather than the x-axis sort. +* **sort** (*string*) – Could be ‘asc’, ‘desc’, ‘hamming’, ‘value’, or ‘value\_desc’. If set to ‘value’ or ‘value\_desc’ the x axis will be sorted by the maximum probability for each bitstring. Defaults to ‘asc’. +* **target\_string** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Target string if ‘sort’ is a distance measure. +* **legend** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of strings to use for labels of the data. The number of entries must match the length of data (if data is a list or 1 if it’s a dict) +* **bar\_labels** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label each bar in histogram with probability value. +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A string to use for the plot title +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. + +**Returns** + +A figure for the rendered distribution, if the `ax` kwarg is not set. + +**Return type** + +matplotlib.Figure + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Matplotlib not available. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – When legend is provided and the length doesn’t match the input data. + +**Examples** + +```python +# Plot two counts in the same figure with legends and colors specified. + +from qiskit.visualization import plot_distribution + +counts1 = {'00': 525, '11': 499} +counts2 = {'00': 511, '11': 514} + +legend = ['First execution', 'Second execution'] + +plot_distribution([counts1, counts2], legend=legend, color=['crimson','midnightblue'], + title="New Distribution") + +# You can sort the bitstrings using different methods. + +counts = {'001': 596, '011': 211, '010': 50, '000': 117, '101': 33, '111': 8, + '100': 6, '110': 3} + +# Sort by the counts in descending order +dist1 = plot_distribution(counts, sort='value_desc') + +# Sort by the hamming distance (the number of bit flips to change from +# one bitstring to the other) from a target string. +dist2 = plot_distribution(counts, sort='hamming', target_string='001') +``` + +![../\_images/qiskit-visualization-plot\_distribution-1\_00.png](/images/api/qiskit/0.46/qiskit-visualization-plot_distribution-1_00.png) + +![../\_images/qiskit-visualization-plot\_distribution-1\_01.png](/images/api/qiskit/0.46/qiskit-visualization-plot_distribution-1_01.png) + +![../\_images/qiskit-visualization-plot\_distribution-1\_02.png](/images/api/qiskit/0.46/qiskit-visualization-plot_distribution-1_02.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_error_map.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_error_map.md new file mode 100644 index 00000000000..0ed2f68688a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_error_map.md @@ -0,0 +1,51 @@ +--- +title: plot_error_map +description: API reference for qiskit.visualization.plot_error_map +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_error_map +--- + + + +# qiskit.visualization.plot\_error\_map + + + +`qiskit.visualization.plot_error_map(backend, figsize=(15, 12), show_title=True, qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/gate_map.py "view source code") + +Plots the error map of a given backend. + +**Parameters** + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – Given backend. +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **show\_title** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show the title or not. +* **qubit\_coordinates** (*Sequence*) – An optional sequence input (list or array being the most common) of 2d coordinates for each qubit. The length of the sequence much mast the number of qubits on the backend. The sequence should be the planar coordinates in a 0-based square grid where each qubit is located. + +**Returns** + +A matplotlib figure showing error map. + +**Return type** + +Figure + +**Raises** + +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – The backend does not provide gate errors for the ‘sx’ gate. +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – If matplotlib or seaborn is not installed. + +**Example** + +```python +from qiskit import QuantumCircuit, execute +from qiskit.visualization import plot_error_map +from qiskit.providers.fake_provider import FakeVigoV2 + +backend = FakeVigoV2() +plot_error_map(backend) +``` + +![../\_images/qiskit-visualization-plot\_error\_map-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_error_map-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_gate_map.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_gate_map.md new file mode 100644 index 00000000000..7ed7fe14ce5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_gate_map.md @@ -0,0 +1,62 @@ +--- +title: plot_gate_map +description: API reference for qiskit.visualization.plot_gate_map +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_gate_map +--- + + + +# qiskit.visualization.plot\_gate\_map + + + +`qiskit.visualization.plot_gate_map(backend, figsize=None, plot_directed=False, label_qubits=True, qubit_size=None, line_width=4, font_size=None, qubit_color=None, qubit_labels=None, line_color=None, font_color='white', ax=None, filename=None, qubit_coordinates=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/gate_map.py "view source code") + +Plots the gate map of a device. + +**Parameters** + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – The backend instance that will be used to plot the device gate map. +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Output figure size (wxh) in inches. +* **plot\_directed** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Plot directed coupling map. +* **label\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label the qubits. +* **qubit\_size** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Size of qubit marker. +* **line\_width** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Width of lines. +* **font\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Font size of qubit labels. +* **qubit\_color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of colors for the qubits +* **qubit\_labels** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of qubit labels +* **line\_color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of colors for each line from coupling\_map. +* **font\_color** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The font color for the qubit labels. +* **ax** (*Axes*) – A Matplotlib axes instance. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. +* **qubit\_coordinates** (*Sequence*) – An optional sequence input (list or array being the most common) of 2d coordinates for each qubit. The length of the sequence much match the number of qubits on the backend. The sequence should be the planar coordinates in a 0-based square grid where each qubit is located. + +**Returns** + +A Matplotlib figure instance. + +**Return type** + +Figure + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if tried to pass a simulator, or if the backend is None, but one of num\_qubits, mpl\_data, or cmap is None. +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – if matplotlib not installed. + +**Example** + +```python +from qiskit import QuantumCircuit, execute +from qiskit.providers.fake_provider import FakeVigoV2 +from qiskit.visualization import plot_gate_map + +backend = FakeVigoV2() + +plot_gate_map(backend) +``` + +![../\_images/qiskit-visualization-plot\_gate\_map-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_gate_map-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_histogram.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_histogram.md new file mode 100644 index 00000000000..f33a5e5687a --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_histogram.md @@ -0,0 +1,84 @@ +--- +title: plot_histogram +description: API reference for qiskit.visualization.plot_histogram +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_histogram +--- + + + +# qiskit.visualization.plot\_histogram + + + +`qiskit.visualization.plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/counts_visualization.py "view source code") + +Plot a histogram of input counts data. + + + Using plot\_histogram() `data` argument with QuasiDistribution, ProbDistribution, or a distribution dictionary is deprecated as of qiskit-terra 0.22.0. It will be removed no earlier than 3 months after the release date. Instead, use `plot_distribution()`. + + +**Parameters** + +* **data** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – This is either a list of dictionaries or a single dict containing the values to represent (ex `{'001': 130}`) +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – String or list of strings for histogram bar colors. +* **number\_to\_keep** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of terms to plot per dataset. The rest is made into a single bar called ‘rest’. If multiple datasets are given, the `number_to_keep` applies to each dataset individually, which may result in more bars than `number_to_keep + 1`. The `number_to_keep` applies to the total values, rather than the x-axis sort. +* **sort** (*string*) – Could be ‘asc’, ‘desc’, ‘hamming’, ‘value’, or ‘value\_desc’. If set to ‘value’ or ‘value\_desc’ the x axis will be sorted by the number of counts for each bitstring. Defaults to ‘asc’. +* **target\_string** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Target string if ‘sort’ is a distance measure. +* **legend** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of strings to use for labels of the data. The number of entries must match the length of data (if data is a list or 1 if it’s a dict) +* **bar\_labels** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Label each bar in histogram with counts value. +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – A string to use for the plot title +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. + +**Returns** + +A figure for the rendered histogram, if the `ax` kwarg is not set. + +**Return type** + +matplotlib.Figure + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Matplotlib not available. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – When legend is provided and the length doesn’t match the input data. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – Input must be Counts or a dict + +**Examples** + +```python +# Plot two counts in the same figure with legends and colors specified. + +from qiskit.visualization import plot_histogram + +counts1 = {'00': 525, '11': 499} +counts2 = {'00': 511, '11': 514} + +legend = ['First execution', 'Second execution'] + +plot_histogram([counts1, counts2], legend=legend, color=['crimson','midnightblue'], + title="New Histogram") + +# You can sort the bitstrings using different methods. + +counts = {'001': 596, '011': 211, '010': 50, '000': 117, '101': 33, '111': 8, + '100': 6, '110': 3} + +# Sort by the counts in descending order +hist1 = plot_histogram(counts, sort='value_desc') + +# Sort by the hamming distance (the number of bit flips to change from +# one bitstring to the other) from a target string. +hist2 = plot_histogram(counts, sort='hamming', target_string='001') +``` + +![../\_images/qiskit-visualization-plot\_histogram-1\_00.png](/images/api/qiskit/0.46/qiskit-visualization-plot_histogram-1_00.png) + +![../\_images/qiskit-visualization-plot\_histogram-1\_01.png](/images/api/qiskit/0.46/qiskit-visualization-plot_histogram-1_01.png) + +![../\_images/qiskit-visualization-plot\_histogram-1\_02.png](/images/api/qiskit/0.46/qiskit-visualization-plot_histogram-1_02.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_state_city.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_city.md new file mode 100644 index 00000000000..13598298d07 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_city.md @@ -0,0 +1,89 @@ +--- +title: plot_state_city +description: API reference for qiskit.visualization.plot_state_city +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_state_city +--- + + + +# qiskit.visualization.plot\_state\_city + + + +`qiskit.visualization.plot_state_city(state, title='', figsize=None, color=None, alpha=1, ax_real=None, ax_imag=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/state_visualization.py "view source code") + +Plot the cityscape of quantum state. + +Plot two 3d bar graphs (two dimensional) of the real and imaginary part of the density matrix rho. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") *or ndarray*) – an N-qubit quantum state. +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a string that represents the plot title +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of len=2 giving colors for real and imaginary components of matrix elements. +* **alpha** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Transparency value for bars +* **ax\_real** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. If this is specified without an ax\_imag only the real component plot will be generated. Additionally, if specified there will be no returned Figure since it is redundant. +* **ax\_imag** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. If this is specified without an ax\_real only the imaginary component plot will be generated. Additionally, if specified there will be no returned Figure since it is redundant. + +**Returns** + +The matplotlib.Figure of the visualization if the `ax_real` and `ax_imag` kwargs are not set + +**Return type** + +[`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure "(in Matplotlib v3.8.2)") + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Requires matplotlib. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – When ‘color’ is not a list of len=2. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – if input is not a valid N-qubit state. + +**Examples** + +```python +# You can choose different colors for the real and imaginary parts of the density matrix. + +from qiskit import QuantumCircuit +from qiskit.quantum_info import DensityMatrix +from qiskit.visualization import plot_state_city + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) + +state = DensityMatrix(qc) +plot_state_city(state, color=['midnightblue', 'crimson'], title="New State City") +``` + +![../\_images/qiskit-visualization-plot\_state\_city-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_city-1.png) + +```python +# You can make the bars more transparent to better see the ones that are behind +# if they overlap. + +import numpy as np +from qiskit.quantum_info import Statevector +from qiskit.visualization import plot_state_city +from qiskit import QuantumCircuit + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) + + +qc = QuantumCircuit(2) +qc.h([0, 1]) +qc.cz(0,1) +qc.ry(np.pi/3, 0) +qc.rx(np.pi/5, 1) + +state = Statevector(qc) +plot_state_city(state, alpha=0.6) +``` + +![../\_images/qiskit-visualization-plot\_state\_city-2.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_city-2.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_state_hinton.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_hinton.md new file mode 100644 index 00000000000..27e62eea163 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_hinton.md @@ -0,0 +1,62 @@ +--- +title: plot_state_hinton +description: API reference for qiskit.visualization.plot_state_hinton +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_state_hinton +--- + + + +# qiskit.visualization.plot\_state\_hinton + + + +`qiskit.visualization.plot_state_hinton(state, title='', figsize=None, ax_real=None, ax_imag=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/state_visualization.py "view source code") + +Plot a hinton diagram for the density matrix of a quantum state. + +The hinton diagram represents the values of a matrix using squares, whose size indicate the magnitude of their corresponding value and their color, its sign. A white square means the value is positive and a black one means negative. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") *or ndarray*) – An N-qubit quantum state. +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a string that represents the plot title +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – file path to save image to. +* **ax\_real** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. If this is specified without an ax\_imag only the real component plot will be generated. Additionally, if specified there will be no returned Figure since it is redundant. +* **ax\_imag** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. If this is specified without an ax\_imag only the real component plot will be generated. Additionally, if specified there will be no returned Figure since it is redundant. + +**Returns** + +The matplotlib.Figure of the visualization if neither ax\_real or ax\_imag is set. + +**Return type** + +[`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure "(in Matplotlib v3.8.2)") + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Requires matplotlib. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – if input is not a valid N-qubit state. + +**Examples** + +```python +import numpy as np +from qiskit import QuantumCircuit +from qiskit.quantum_info import DensityMatrix +from qiskit.visualization import plot_state_hinton + +qc = QuantumCircuit(2) +qc.h([0, 1]) +qc.cz(0,1) +qc.ry(np.pi/3 , 0) +qc.rx(np.pi/5, 1) + +state = DensityMatrix(qc) +plot_state_hinton(state, title="New Hinton Plot") +``` + +![../\_images/qiskit-visualization-plot\_state\_hinton-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_hinton-1.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_state_paulivec.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_paulivec.md new file mode 100644 index 00000000000..0ae95376352 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_paulivec.md @@ -0,0 +1,92 @@ +--- +title: plot_state_paulivec +description: API reference for qiskit.visualization.plot_state_paulivec +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_state_paulivec +--- + + + +# qiskit.visualization.plot\_state\_paulivec + + + +`qiskit.visualization.plot_state_paulivec(state, title='', figsize=None, color=None, ax=None, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/state_visualization.py "view source code") + +Plot the Pauli-vector representation of a quantum state as bar graph. + +The Pauli-vector of a density matrix $\rho$ is defined by the expectation of each possible tensor product of single-qubit Pauli operators (including the identity), that is + +$$ +\rho = \frac{1}{2^n} \sum_{\sigma \in \{I, X, Y, Z\}^{\otimes n}} + \mathrm{Tr}(\sigma \rho) \sigma. +$$ + +This function plots the coefficients $\mathrm{Tr}(\sigma\rho)$ as bar graph. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") *or ndarray*) – an N-qubit quantum state. +* **title** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – a string that represents the plot title +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **color** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Color of the coefficient value bars. +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. + +**Returns** + +The matplotlib.Figure of the visualization if the `ax` kwarg is not set + +**Return type** + +[`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure "(in Matplotlib v3.8.2)") + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Requires matplotlib. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – if input is not a valid N-qubit state. + +**Examples** + +```python +# You can set a color for all the bars. + +from qiskit import QuantumCircuit +from qiskit.quantum_info import Statevector +from qiskit.visualization import plot_state_paulivec + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) + +state = Statevector(qc) +plot_state_paulivec(state, color='midnightblue', title="New PauliVec plot") +``` + +![../\_images/qiskit-visualization-plot\_state\_paulivec-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_paulivec-1.png) + +```python +# If you introduce a list with less colors than bars, the color of the bars will +# alternate following the sequence from the list. + +import numpy as np +from qiskit.quantum_info import DensityMatrix +from qiskit import QuantumCircuit +from qiskit.visualization import plot_state_paulivec + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) + +qc = QuantumCircuit(2) +qc.h([0, 1]) +qc.cz(0, 1) +qc.ry(np.pi/3, 0) +qc.rx(np.pi/5, 1) + +matrix = DensityMatrix(qc) +plot_state_paulivec(matrix, color=['crimson', 'midnightblue', 'seagreen']) +``` + +![../\_images/qiskit-visualization-plot\_state\_paulivec-2.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_paulivec-2.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.plot_state_qsphere.md b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_qsphere.md new file mode 100644 index 00000000000..8e2d662146c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.plot_state_qsphere.md @@ -0,0 +1,81 @@ +--- +title: plot_state_qsphere +description: API reference for qiskit.visualization.plot_state_qsphere +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.plot_state_qsphere +--- + + + +# qiskit.visualization.plot\_state\_qsphere + + + +`qiskit.visualization.plot_state_qsphere(state, figsize=None, ax=None, show_state_labels=True, show_state_phases=False, use_degrees=False, *, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/state_visualization.py "view source code") + +Plot the qsphere representation of a quantum state. Here, the size of the points is proportional to the probability of the corresponding term in the state and the color represents the phase. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") *or ndarray*) – an N-qubit quantum state. +* **figsize** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – Figure size in inches. +* **ax** ([*matplotlib.axes.Axes*](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes "(in Matplotlib v3.8.2)")) – An optional Axes object to be used for the visualization output. If none is specified a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. +* **show\_state\_labels** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – An optional boolean indicating whether to show labels for each basis state. +* **show\_state\_phases** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – An optional boolean indicating whether to show the phase for each basis state. +* **use\_degrees** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – An optional boolean indicating whether to use radians or degrees for the phase values in the plot. + +**Returns** + +A matplotlib figure instance if the `ax` kwarg is not set + +**Return type** + +[`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure "(in Matplotlib v3.8.2)") + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Requires matplotlib. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – if input is not a valid N-qubit state. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Input statevector does not have valid dimensions. + +**Examples** + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import Statevector +from qiskit.visualization import plot_state_qsphere + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) + +state = Statevector(qc) +plot_state_qsphere(state) +``` + +![../\_images/qiskit-visualization-plot\_state\_qsphere-1.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_qsphere-1.png) + +```python +# You can show the phase of each state and use +# degrees instead of radians + +from qiskit.quantum_info import DensityMatrix +import numpy as np +from qiskit import QuantumCircuit +from qiskit.visualization import plot_state_qsphere + +qc = QuantumCircuit(2) +qc.h([0, 1]) +qc.cz(0,1) +qc.ry(np.pi/3, 0) +qc.rx(np.pi/5, 1) +qc.z(1) + +matrix = DensityMatrix(qc) +plot_state_qsphere(matrix, + show_state_phases = True, use_degrees = True) +``` + +![../\_images/qiskit-visualization-plot\_state\_qsphere-2.png](/images/api/qiskit/0.46/qiskit-visualization-plot_state_qsphere-2.png) + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXDebugging.md b/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXDebugging.md new file mode 100644 index 00000000000..2928b54b7f0 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXDebugging.md @@ -0,0 +1,113 @@ +--- +title: IQXDebugging +description: API reference for qiskit.visualization.pulse.IQXDebugging +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.visualization.pulse.IQXDebugging +--- + +# IQXDebugging + + + +`qiskit.visualization.pulse.IQXDebugging(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/pulse_v2/stylesheet.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +Pulse stylesheet for pulse programmers. Show details of instructions. + +\# TODO: add more generators + +* Generate stepwise waveform envelope with latex pulse names. +* Generate annotation for waveform height. +* Apply phase modulation to waveforms. +* Plot frame change symbol with raw operand values. +* Show chart name and channel frequency. +* Show snapshot and barrier. +* Show acquire channels. +* Channels are sorted by index and control channels are added to the end. + +## Methods + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXSimple.md b/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXSimple.md new file mode 100644 index 00000000000..8d15cb026c5 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXSimple.md @@ -0,0 +1,110 @@ +--- +title: IQXSimple +description: API reference for qiskit.visualization.pulse.IQXSimple +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.visualization.pulse.IQXSimple +--- + +# IQXSimple + + + +`qiskit.visualization.pulse.IQXSimple(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/pulse_v2/stylesheet.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +Simple pulse stylesheet without channel notation. + +* Generate stepwise waveform envelope with latex pulse names. +* Apply phase modulation to waveforms. +* Do not show frame changes. +* Show chart name. +* Do not show snapshot and barrier. +* Do not show acquire channels. +* Channels are sorted by qubit index. + +## Methods + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXStandard.md b/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXStandard.md new file mode 100644 index 00000000000..23d0b0883bf --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.pulse.IQXStandard.md @@ -0,0 +1,110 @@ +--- +title: IQXStandard +description: API reference for qiskit.visualization.pulse.IQXStandard +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit.visualization.pulse.IQXStandard +--- + +# IQXStandard + + + +`qiskit.visualization.pulse.IQXStandard(**kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/pulse_v2/stylesheet.py "view source code") + +Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +Standard pulse stylesheet. + +* Generate stepwise waveform envelope with latex pulse names. +* Apply phase modulation to waveforms. +* Plot frame change symbol with formatted operand values. +* Show chart name with scaling factor. +* Show snapshot and barrier. +* Do not show acquire channels. +* Channels are sorted by index and control channels are added to the end. + +## Methods + +### clear + + + +`clear() → None.  Remove all items from D.` + +### copy + + + +`copy() → a shallow copy of D` + +### fromkeys + + + +`fromkeys(value=None, /)` + +Create a new dictionary with keys from iterable and values set to value. + +### get + + + +`get(key, default=None, /)` + +Return the value for key if key is in the dictionary, else default. + +### items + + + +`items() → a set-like object providing a view on D's items` + +### keys + + + +`keys() → a set-like object providing a view on D's keys` + +### pop + + + +`pop(k[, d]) → v, remove specified key and return the corresponding value.` + +If key is not found, default is returned if given, otherwise KeyError is raised + +### popitem + + + +`popitem()` + +Remove and return a (key, value) pair as a 2-tuple. + +Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty. + +### setdefault + + + +`setdefault(key, default=None, /)` + +Insert key with a value of default if key is not in the dictionary. + +Return the value for key if key is in the dictionary, else default. + +### update + + + +`update([E, ]**F) → None.  Update D from dict/iterable E and F.` + +If E is present and has a .keys() method, then does: for k in E: D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] + +### values + + + +`values() → an object providing a view on D's values` + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.pulse_drawer.md b/docs/api/qiskit/0.46/qiskit.visualization.pulse_drawer.md new file mode 100644 index 00000000000..65cdb11761c --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.pulse_drawer.md @@ -0,0 +1,323 @@ +--- +title: pulse_drawer +description: API reference for qiskit.visualization.pulse_drawer +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.pulse_drawer +--- + + + +# qiskit.visualization.pulse\_drawer + + + +`qiskit.visualization.pulse_drawer(program, style=None, backend=None, time_range=None, time_unit='dt', disable_channels=None, show_snapshot=True, show_framechange=True, show_waveform_info=True, show_barrier=True, plotter='mpl2d', axis=None)` + +Generate visualization data for pulse programs. + +**Parameters** + +* **program** ([*Waveform*](qiskit.pulse.library.Waveform "qiskit.pulse.library.waveform.Waveform") *|*[*ParametricPulse*](qiskit.pulse.library.ParametricPulse "qiskit.pulse.library.parametric_pulses.ParametricPulse") *|*[*SymbolicPulse*](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.symbolic_pulses.SymbolicPulse") *|*[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")) – Program to visualize. This program can be arbitrary Qiskit Pulse program, such as `Waveform`, `ParametricPulse`, `SymbolicPulse`, [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") and [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"). + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. See also the stylesheet section for details of configuration keys. + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple `(tmin, tmax)`. + +* **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either `dt` or `ns`. The unit of `ns` is available only when `backend` object is provided. + +* **disable\_channels** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – A control property to show specific pulse channel. Pulse channel instances provided as a list is not shown in the output image. + +* **show\_snapshot** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show snapshot instructions. + +* **show\_framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show frame change instructions. The frame change represents instructions that modulate phase or frequency of pulse channels. + +* **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show waveform annotations, i.e. name, of waveforms. Set `True` to show additional information about waveforms. + +* **show\_barrier** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show barrier lines. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl2d: Matplotlib API for 2D image generation. + Matplotlib API to generate 2D image. Charts are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as `axis` input. + ``` + + axis and style kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given `axis` instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details. + +**Returns** + +Visualization output data. The returned data type depends on the plotter. If matplotlib family is specified, this will be a matplotlib.pyplot.Figure data. The returned data is generated by the `get_image()` method of the specified plotter API. + +**Style Dict Details** + +The stylesheet kwarg contains numerous options that define the style of the output pulse visualization. The stylesheet options can be classified into formatter, generator and layout. Those options available in the stylesheet are defined below: + +**Parameters** + +* **formatter.general.fig\_width** – Width of output image (default 13). + +* **formatter.general.fig\_chart\_height** – Height of output image per chart. The height of each chart is multiplied with this factor and the sum of all chart heights becomes the height of output image (default 1.5). + +* **formatter.general.vertical\_resolution** – Vertical resolution of the pulse envelope. The change of data points below this limit is ignored (default 1e-6). + +* **formatter.general.max\_scale** – Maximum scaling factor of each chart. This factor is considered when chart auto-scaling is enabled (default 100). + +* **formatter.color.waveforms** – + + A dictionary of the waveform colors to use for each element type in the output visualization. The default values are: + + ```python + { + 'W': `['#648fff', '#002999']`, + 'D': `['#648fff', '#002999']`, + 'U': `['#ffb000', '#994A00']`, + 'M': `['#dc267f', '#760019']`, + 'A': `['#dc267f', '#760019']` + } + ``` + +* **formatter.color.baseline** – Color code of lines of zero line of each chart (default ‘#000000’). + +* **formatter.color.barrier** – Color code of lines of barrier (default ‘#222222’). + +* **formatter.color.background** – Color code of the face color of canvas (default ‘#f2f3f4’). + +* **formatter.color.fig\_title** – Color code of the figure title text (default ‘#000000’). + +* **formatter.color.annotate** – Color code of annotation texts in the canvas (default ‘#222222’). + +* **formatter.color.frame\_change** – Color code of the symbol for frame changes (default ‘#000000’). + +* **formatter.color.snapshot** – Color code of the symbol for snapshot (default ‘#000000’) + +* **formatter.color.opaque\_shape** – Color code of the face and edge of opaque shape box (default \[‘#fffacd’, ‘#000000’]) + +* **formatter.color.axis\_label** – Color code of axis labels (default ‘#000000’). + +* **formatter.alpha.fill\_waveform** – Transparency of waveforms. A value in the range from 0 to 1. The value 0 gives completely transparent waveforms (default 0.3). + +* **formatter.alpha.baseline** – Transparency of base lines. A value in the range from 0 to 1. The value 0 gives completely transparent base lines (default 1.0). + +* **formatter.alpha.barrier** – Transparency of barrier lines. A value in the range from 0 to 1. The value 0 gives completely transparent barrier lines (default 0.7). + +* **formatter.alpha.opaque\_shape** – Transparency of opaque shape box. A value in the range from 0 to 1. The value 0 gives completely transparent barrier lines (default 0.7). + +* **formatter.layer.fill\_waveform** – Layer index of waveforms. Larger number comes in the front of the output image (default 2). + +* **formatter.layer.baseline** – Layer index of baselines. Larger number comes in the front of the output image (default 1). + +* **formatter.layer.barrier** – Layer index of barrier lines. Larger number comes in the front of the output image (default 1). + +* **formatter.layer.annotate** – Layer index of annotations. Larger number comes in the front of the output image (default 5). + +* **formatter.layer.axis\_label** – Layer index of axis labels. Larger number comes in the front of the output image (default 5). + +* **formatter.layer.frame\_change** – Layer index of frame change symbols. Larger number comes in the front of the output image (default 4). + +* **formatter.layer.snapshot** – Layer index of snapshot symbols. Larger number comes in the front of the output image (default 3). + +* **formatter.layer.fig\_title** – Layer index of the figure title. Larger number comes in the front of the output image (default 6). + +* **formatter.margin.top** – Margin from the top boundary of the figure canvas to the surface of the first chart (default 0.5). + +* **formatter.margin.bottom** – Margin from the bottom boundary of the figure canvas to the surface of the last chart (default 0.5). + +* **formatter.margin.left\_percent** – Margin from the left boundary of the figure canvas to the zero point of the horizontal axis. The value is in units of percentage of the whole program duration. If the duration is 100 and the value of 0.5 is set, this keeps left margin of 5 (default 0.05). + +* **formatter.margin.right\_percent** – Margin from the right boundary of the figure canvas to the left limit of the horizontal axis. The value is in units of percentage of the whole program duration. If the duration is 100 and the value of 0.5 is set, this keeps right margin of 5 (default 0.05). + +* **formatter.margin.between\_channel** – Vertical margin between charts (default 0.2). + +* **formatter.label\_offset.pulse\_name** – Offset of pulse name annotations from the chart baseline (default 0.3). + +* **formatter.label\_offset.chart\_info** – Offset of chart info annotations from the chart baseline (default 0.3). + +* **formatter.label\_offset.frame\_change** – Offset of frame change annotations from the chart baseline (default 0.3). + +* **formatter.label\_offset.snapshot** – Offset of snapshot annotations from the chart baseline (default 0.3). + +* **formatter.text\_size.axis\_label** – Text size of axis labels (default 15). + +* **formatter.text\_size.annotate** – Text size of annotations (default 12). + +* **formatter.text\_size.frame\_change** – Text size of frame change symbols (default 20). + +* **formatter.text\_size.snapshot** – Text size of snapshot symbols (default 20). + +* **formatter.text\_size.fig\_title** – Text size of the figure title (default 15). + +* **formatter.text\_size.axis\_break\_symbol** – Text size of axis break symbols (default 15). + +* **formatter.line\_width.fill\_waveform** – Line width of the fringe of filled waveforms (default 0). + +* **formatter.line\_width.axis\_break** – Line width of axis breaks. The axis break line paints over other drawings with the background face color (default 6). + +* **formatter.line\_width.baseline** – Line width of base lines (default 1) + +* **formatter.line\_width.barrier** – Line width of barrier lines (default 1). + +* **formatter.line\_width.opaque\_shape** – Line width of opaque shape box (default 1). + +* **formatter.line\_style.fill\_waveform** – Line style of the fringe of filled waveforms. This conforms to the line style spec of matplotlib (default ‘-’). + +* **formatter.line\_style.baseline** – Line style of base lines. This conforms to the line style spec of matplotlib (default ‘-’). + +* **formatter.line\_style.barrier** – Line style of barrier lines. This conforms to the line style spec of matplotlib (default ‘:’). + +* **formatter.line\_style.opaque\_shape** – Line style of opaque shape box. This conforms to the line style spec of matplotlib (default ‘–’). + +* **formatter.channel\_scaling.drive** – Default scaling value of drive channel waveforms (default 1.0). + +* **formatter.channel\_scaling.control** – Default scaling value of control channel waveforms (default 1.0). + +* **formatter.channel\_scaling.measure** – Default scaling value of measure channel waveforms (default 1.0). + +* **formatter.channel\_scaling.acquire** – Default scaling value of acquire channel waveforms (default 1.0). + +* **formatter.channel\_scaling.pos\_spacing** – Minimum height of chart above the baseline. Chart top is determined based on the maximum height of waveforms associated with the chart. If the maximum height is below this value, this value is set as the chart top (default 0.1). + +* **formatter.channel\_scaling.neg\_spacing** – Minimum height of chart below the baseline. Chart bottom is determined based on the minimum height of waveforms associated with the chart. If the minimum height is above this value, this value is set as the chart bottom (default -0.1). + +* **formatter.box\_width.opaque\_shape** – Default box length of the waveform representation when the instruction is parameterized and duration is not bound or not defined. Value is units in dt (default: 150). + +* **formatter.box\_height.opaque\_shape** – Default box height of the waveform representation when the instruction is parameterized (default: 0.4). + +* **formatter.axis\_break.length** – Waveform or idle time duration that axis break is applied. Intervals longer than this value are truncated. The value is in units of data points (default 3000). + +* **formatter.axis\_break.max\_length** – Length of new waveform or idle time duration after axis break is applied. Longer intervals are truncated to this length (default 1000). + +* **formatter.control.fill\_waveform** – Set True to fill waveforms with face color (default True). When you disable this option, you should set finite line width to formatter.line\_width.fill\_waveform, otherwise nothing will appear in the graph. + +* **formatter.control.apply\_phase\_modulation** – Set True to apply phase modulation to the waveforms (default True). + +* **formatter.control.show\_snapshot\_channel** – Set True to show snapshot instructions (default True). + +* **formatter.control.show\_acquire\_channel** – Set True to show acquire channels (default True). + +* **formatter.control.show\_empty\_channel** – Set True to show charts without any waveforms (default True). + +* **formatter.control.auto\_chart\_scaling** – Set True to apply auto-scaling to charts (default True). + +* **formatter.control.axis\_break** – Set True to apply axis break for long intervals (default True). + +* **formatter.unicode\_symbol.frame\_change** – Text that represents the symbol of frame change. This text is used when the plotter doesn’t support latex (default u’↺’). + +* **formatter.unicode\_symbol.snapshot** – Text that represents the symbol of snapshot. This text is used when the plotter doesn’t support latex (default u’↯’). + +* **formatter.unicode\_symbol.phase\_parameter** – Text that represents the symbol of parameterized phase value. This text is used when the plotter doesn’t support latex (default u’θ’). + +* **formatter.unicode\_symbol.freq\_parameter** – Text that represents the symbol of parameterized frequency value. This text is used when the plotter doesn’t support latex (default ‘f’). + +* **formatter.latex\_symbol.frame\_change** – Latex text that represents the symbol of frame change (default r’circlearrowleft’). + +* **formatter.latex\_symbol.snapshot** – Latex text that represents the symbol of snapshot (default ‘’). + +* **formatter.latex\_symbol.phase\_parameter** – Latex text that represents the symbol of parameterized phase value (default r’ heta’). + +* **formatter.latex\_symbol.freq\_parameter** – Latex text that represents the symbol of parameterized frequency value (default ‘f’). + +* **generator.waveform** – List of callback functions that generates drawing for waveforms. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the pulse drawer. See `waveform` for more details. No default generator is set. + +* **generator.frame** – List of callback functions that generates drawing for frame changes. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the pulse drawer. See `frame` for more details. No default generator is set. + +* **generator.chart** – List of callback functions that generates drawing for charts. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the pulse drawer. See `chart` for more details. No default generator is set. + +* **generator.snapshot** – List of callback functions that generates drawing for snapshots. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the pulse drawer. See `snapshot` for more details. No default generator is set. + +* **generator.barrier** – List of callback functions that generates drawing for barriers. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the pulse drawer. See `barrier` for more details. No default generator is set. + +* **layout.chart\_channel\_map** – Callback function that determines the relationship between pulse channels and charts. See `layout` for more details. No default layout is set. + +* **layout.time\_axis\_map** – Callback function that determines the layout of horizontal axis labels. See `layout` for more details. No default layout is set. + +* **layout.figure\_title** – Callback function that generates a string for the figure title. See `layout` for more details. No default layout is set. + +**Examples** + +To visualize a pulse program, you can call this function with set of control arguments. Most of appearance of the output image can be controlled by the stylesheet. + +Drawing with the default stylesheet. + +```python +from qiskit import QuantumCircuit, transpile, schedule +from qiskit.visualization.pulse_v2 import draw +from qiskit.providers.fake_provider import FakeBoeblingen + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) +qc.measure_all() +qc = transpile(qc, FakeBoeblingen(), layout_method='trivial') +sched = schedule(qc, FakeBoeblingen()) + +draw(sched, backend=FakeBoeblingen()) +``` + +![../\_images/qiskit-visualization-pulse\_drawer-1.png](/images/api/qiskit/0.46/qiskit-visualization-pulse_drawer-1.png) + +Drawing with the stylesheet suited for publication. + +```python +from qiskit import QuantumCircuit, transpile, schedule +from qiskit.visualization.pulse_v2 import draw, IQXSimple +from qiskit.providers.fake_provider import FakeBoeblingen + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) +qc.measure_all() +qc = transpile(qc, FakeBoeblingen(), layout_method='trivial') +sched = schedule(qc, FakeBoeblingen()) + +draw(sched, style=IQXSimple(), backend=FakeBoeblingen()) +``` + +![../\_images/qiskit-visualization-pulse\_drawer-2.png](/images/api/qiskit/0.46/qiskit-visualization-pulse_drawer-2.png) + +Drawing with the stylesheet suited for program debugging. + +```python +from qiskit import QuantumCircuit, transpile, schedule +from qiskit.visualization.pulse_v2 import draw, IQXDebugging +from qiskit.providers.fake_provider import FakeBoeblingen + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0, 1) +qc.measure_all() +qc = transpile(qc, FakeBoeblingen(), layout_method='trivial') +sched = schedule(qc, FakeBoeblingen()) + +draw(sched, style=IQXDebugging(), backend=FakeBoeblingen()) +``` + +![../\_images/qiskit-visualization-pulse\_drawer-3.png](/images/api/qiskit/0.46/qiskit-visualization-pulse_drawer-3.png) + +You can partially customize a preset stylesheet when initializing it. + +```python +my_style = { + 'formatter.channel_scaling.drive': 5, + 'formatter.channel_scaling.control': 1, + 'formatter.channel_scaling.measure': 5 +} +style = IQXStandard(**my_style) +# draw +draw(sched, style=style, backend=FakeBoeblingen()) +``` + +In the same way as above, you can create custom generator or layout functions and update the existing stylesheet with custom functions. This feature enables you to customize most of the appearance of the output image without modifying the codebase. + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – When required visualization package is not installed. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – When invalid plotter API or invalid time range is specified. + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.timeline_drawer.md b/docs/api/qiskit/0.46/qiskit.visualization.timeline_drawer.md new file mode 100644 index 00000000000..1800e433bb1 --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.timeline_drawer.md @@ -0,0 +1,321 @@ +--- +title: timeline_drawer +description: API reference for qiskit.visualization.timeline_drawer +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.timeline_drawer +--- + + + +# qiskit.visualization.timeline\_drawer + + + +`qiskit.visualization.timeline_drawer(program, style=None, time_range=None, disable_bits=None, show_clbits=None, show_idle=None, show_barriers=None, show_delays=None, show_labels=True, plotter='mpl', axis=None, filename=None)` + +Generate visualization data for scheduled circuit programs. + +**Parameters** + +* **program** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – Program to visualize. This program should be a QuantumCircuit which is transpiled with a scheduling\_method, thus containing gate time information. + +* **style** ([*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)")*] | None*) – Stylesheet options. This can be dictionary or preset stylesheet classes. See `IQXStandard`, `IQXSimple`, and `IQXDebugging` for details of preset stylesheets. See also the stylesheet section for details of configuration keys. + +* **time\_range** ([*Tuple*](https://docs.python.org/3/library/typing.html#typing.Tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. + +* **disable\_bits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[Bits] | None*) – List of qubits of classical bits not shown in the output image. + +* **show\_clbits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – A control property to show classical bits. Set True to show classical bits. + +* **show\_idle** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – A control property to show idle timeline. Set True to show timeline without gates. + +* **show\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – A control property to show barrier instructions. Set True to show barrier instructions. + +* **show\_delays** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – A control property to show delay instructions. Set True to show delay instructions. + +* **show\_labels** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – A control property to show annotations, i.e. name, of gates. Set True to show annotations. + +* **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – + + Name of plotter API to generate an output image. One of following APIs should be specified: + + ```python + mpl: Matplotlib API + Matplotlib API to generate 2D image. Timelines are placed along y axis with + vertical offset. This API takes matplotlib.axes.Axes as `axis` input. + ``` + + axis and style kwargs may depend on the plotter. + +* **axis** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.12)") *| None*) – Arbitrary object passed to the plotter. If this object is provided, the plotters uses given axis instead of internally initializing a figure object. This object format depends on the plotter. See plotters section for details. + +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – If provided the output image is dumped into a file under the filename. + +**Returns** + +Visualization output data. + +The returned data type depends on the plotter. If matplotlib family is specified, this will be a matplotlib.pyplot.Figure data. The returned data is generated by the .get\_image method of the specified plotter API. + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – When required visualization package is not installed. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – When invalid plotter API is specified. + +**Style Dict Details** + +The stylesheet kwarg contains numerous options that define the style of the output timeline visualization. The stylesheet options can be classified into formatter, generator and layout. Those options available in the stylesheet are defined below: + +**Parameters** + +* **formatter.general.fig\_width** – Width of output image (default 14). + +* **formatter.general.fig\_unit\_height** – Height of output image per timeline. The sum of all timeline becomes the height of the output image (default 0.8). + +* **formatter.general.dpi** – Dot per inch of image if filename is set (default 150). + +* **formatter.margin.top** – Margin from the top boundary of the figure canvas to the zero line of the first time slot (default 0.5). + +* **formatter.margin.bottom** – Margin from the bottom boundary of the figure canvas to the zero lien of the last time slot (default 0.5). + +* **formatter.margin.left\_percent** – Margin from the left boundary of the figure canvas to the left limit of the horizontal axis. The value is in units of percentage of the whole program duration. If the duration is 100 and the value of 0.5 is set, this keeps left margin of 5 (default 0.02). + +* **formatter.margin.right\_percent** – Margin from the right boundary of the figure canvas to the right limit of the horizontal axis. The value is in units of percentage of the whole program duration. If the duration is 100 and the value of 0.5 is set, this keeps right margin of 5 (default 0.02). + +* **formatter.margin.link\_interval\_percent** – Allowed overlap of gate links. If multiple gate links are drawing within this range, links are horizontally shifted not to overlap with each other. The value is in units of percentage of the whole program duration (default 0.01). + +* **formatter.time\_bucket.edge\_dt** – The length of round edge of gate boxes. Gate boxes are smoothly faded in and out from the zero line. This value is in units of the system cycle time dt (default 10). + +* **formatter.margin.minimum\_duration** – Minimum scheduled circuit duration. If the duration of input circuit is below this value, horizontal limit is set based on this value. This value is in units of the system cycle time dt (default 50). + +* **formatter.color.background** – Color code of the face color of canvas (default #FFFFFF). + +* **formatter.color.timeslot** – Face color of the time slot box (default #DDDDDD). + +* **formatter.color.gate\_name** – Text color of the gate name annotations (default #000000). + +* **formatter.color.bit\_name** – Text color of the bit label annotations (default #000000). + +* **formatter.color.barrier** – Line color of barriers (default #222222). + +* **formatter.color.gates** – + + A dictionary of the gate box or gate symbol colors to use for each element type in the output visualization. The default values are: + + ```python + { + 'u0': '#FA74A6', + 'u1': '#000000', + 'u2': '#FA74A6', + 'u3': '#FA74A6', + 'id': '#05BAB6', + 'sx': '#FA74A6', + 'sxdg': '#FA74A6', + 'x': '#05BAB6', + 'y': '#05BAB6', + 'z': '#05BAB6', + 'h': '#6FA4FF', + 'cx': '#6FA4FF', + 'cy': '#6FA4FF', + 'cz': '#6FA4FF', + 'swap': '#6FA4FF', + 's': '#6FA4FF', + 'sdg': '#6FA4FF', + 'dcx': '#6FA4FF', + 'iswap': '#6FA4FF', + 't': '#BB8BFF', + 'tdg': '#BB8BFF', + 'r': '#BB8BFF', + 'rx': '#BB8BFF', + 'ry': '#BB8BFF', + 'rz': '#000000', + 'reset': '#808080', + 'measure': '#808080' + } + ``` + + You must specify all the necessary values if using this. If a gate name is not specified, the color in formatter.color.default\_gate is applied. + +* **formatter.color.default\_gate** – Default gate color. This color is applied when a gate name to visualize is not contained in the dictionary of formatter.color.gates (default #BB8BFF). + +* **formatter.latex\_symbol.gates** – + + A dictionary of latex representation of gate names to use for each element type in the output visualization. The default values are: + + ```python + { + 'u0': r'{\rm U}_0', + 'u1': r'{\rm U}_1', + 'u2': r'{\rm U}_2', + 'u3': r'{\rm U}_3', + 'id': r'{\rm Id}', + 'x': r'{\rm X}', + 'y': r'{\rm Y}', + 'z': r'{\rm Z}', + 'h': r'{\rm H}', + 'cx': r'{\rm CX}', + 'cy': r'{\rm CY}', + 'cz': r'{\rm CZ}', + 'swap': r'{\rm SWAP}', + 's': r'{\rm S}', + 'sdg': r'{\rm S}^\dagger', + 'sx': r'{\rm √X}', + 'sxdg': r'{\rm √X}^\dagger', + 'dcx': r'{\rm DCX}', + 'iswap': r'{\rm iSWAP}', + 't': r'{\rm T}', + 'tdg': r'{\rm T}^\dagger', + 'r': r'{\rm R}', + 'rx': r'{\rm R}_x', + 'ry': r'{\rm R}_y', + 'rz': r'{\rm R}_z', + 'reset': r'|0\rangle', + 'measure': r'{\rm Measure}' + } + ``` + + You must specify all the necessary values if using this. There is no provision for passing an incomplete dict in. + +* **formatter.latex\_symbol.frame\_change** – Latex representation of the frame change symbol (default r\`circlearrowleft\`). + +* **formatter.unicode\_symbol.frame\_change** – Unicode representation of the frame change symbol (default u’u21BA’). + +* **formatter.box\_height.gate** – Height of gate box (default 0.5). + +* **formatter.box\_height.timeslot** – Height of time slot (default 0.6). + +* **formatter.layer.gate** – Layer index of gate boxes. Larger number comes in the front of the output image (default 3). + +* **formatter.layer.timeslot** – Layer index of time slots. Larger number comes in the front of the output image (default 0). + +* **formatter.layer.gate\_name** – Layer index of gate name annotations. Larger number comes in the front of the output image (default 5). + +* **formatter.layer.bit\_name** – Layer index of bit labels. Larger number comes in the front of the output image (default 5). + +* **formatter.layer.frame\_change** – Layer index of frame change symbols. Larger number comes in the front of the output image (default 4). + +* **formatter.layer.barrier** – Layer index of barrier lines. Larger number comes in the front of the output image (default 1). + +* **formatter.layer.gate\_link** – Layer index of gate link lines. Larger number comes in the front of the output image (default 2). + +* **formatter.alpha.gate** – Transparency of gate boxes. A value in the range from 0 to 1. The value 0 gives completely transparent boxes (default 1.0). + +* **formatter.alpha.timeslot** – Transparency of time slots. A value in the range from 0 to 1. The value 0 gives completely transparent boxes (default 0.7). + +* **formatter.alpha.barrier** – Transparency of barrier lines. A value in the range from 0 to 1. The value 0 gives completely transparent lines (default 0.5). + +* **formatter.alpha.gate\_link** – Transparency of gate link lines. A value in the range from 0 to 1. The value 0 gives completely transparent lines (default 0.8). + +* **formatter.line\_width.gate** – Line width of the fringe of gate boxes (default 0). + +* **formatter.line\_width.timeslot** – Line width of the fringe of time slots (default 0). + +* **formatter.line\_width.barrier** – Line width of barrier lines (default 3). + +* **formatter.line\_width.gate\_link** – Line width of gate links (default 3). + +* **formatter.line\_style.barrier** – Line style of barrier lines. This conforms to the line style spec of matplotlib (default ‘-’). + +* **formatter.line\_style.gate\_link** – Line style of gate link lines. This conforms to the line style spec of matplotlib (default ‘-’). + +* **formatter.text\_size.gate\_name** – Text size of gate name annotations (default 12). + +* **formatter.text\_size.bit\_name** – Text size of bit labels (default 15). + +* **formatter.text\_size.frame\_change** – Text size of frame change symbols (default 18). + +* **formatter.text\_size.axis\_label** – Text size of axis labels (default 13). + +* **formatter.label\_offset.frame\_change** – Offset of zero duration gate name annotations from the zero line of time slot (default 0.25). + +* **formatter.control.show\_idle** – Set True to show time slots without gate (default True). + +* **formatter.control.show\_clbits** – Set True to show time slots of classical bits (default True). + +* **formatter.control.show\_barriers** – Set True to show barriers (default True). + +* **formatter.control.show\_delays** – Set True to show delay boxes (default True). + +* **generator.gates** – List of callback functions that generates drawings for gates. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the timeline drawer. See `generators` for more details. No default generator is set (default \[]). + +* **generator.bits** – List of callback functions that generates drawings for bit labels and time slots. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the timeline drawer. See `generators` for more details. No default generator is set (default \[]). + +* **generator.barriers** – List of callback functions that generates drawings for barriers. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the timeline drawer. See `generators` for more details. No default generator is set (default \[]). + +* **generator.gate\_links** – List of callback functions that generates drawings for gate links. Arbitrary callback functions satisfying the generator format can be set here. There are some default generators in the timeline drawer. See `generators` for more details. No default generator is set (default \[]). + +* **layout.bit\_arrange** – Callback function that sorts bits. See `layouts` for more details. No default layout is set. (default None). + +* **layout.time\_axis\_map** – Callback function that determines the layout of horizontal axis labels. See `layouts` for more details. No default layout is set. (default None). + +**Examples** + +To visualize a scheduled circuit program, you can call this function with set of control arguments. Most of appearance of the output image can be controlled by the stylesheet. + +Drawing with the default stylesheet. + +```python +from qiskit import QuantumCircuit, transpile, schedule +from qiskit.visualization.timeline import draw +from qiskit.providers.fake_provider import FakeBoeblingen + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0,1) + +qc = transpile(qc, FakeBoeblingen(), scheduling_method='alap', layout_method='trivial') +draw(qc) +``` + +![../\_images/qiskit-visualization-timeline\_drawer-1.png](/images/api/qiskit/0.46/qiskit-visualization-timeline_drawer-1.png) + +Drawing with the simple stylesheet. + +```python +from qiskit import QuantumCircuit, transpile, schedule +from qiskit.visualization.timeline import draw, IQXSimple +from qiskit.providers.fake_provider import FakeBoeblingen + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0,1) + +qc = transpile(qc, FakeBoeblingen(), scheduling_method='alap', layout_method='trivial') +draw(qc, style=IQXSimple()) +``` + +![../\_images/qiskit-visualization-timeline\_drawer-2.png](/images/api/qiskit/0.46/qiskit-visualization-timeline_drawer-2.png) + +Drawing with the stylesheet suited for program debugging. + +```python +from qiskit import QuantumCircuit, transpile, schedule +from qiskit.visualization.timeline import draw, IQXDebugging +from qiskit.providers.fake_provider import FakeBoeblingen + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0,1) + +qc = transpile(qc, FakeBoeblingen(), scheduling_method='alap', layout_method='trivial') +draw(qc, style=IQXDebugging()) +``` + +![../\_images/qiskit-visualization-timeline\_drawer-3.png](/images/api/qiskit/0.46/qiskit-visualization-timeline_drawer-3.png) + +You can partially customize a preset stylesheet when call it: + +```python +my_style = { + 'formatter.general.fig_width': 16, + 'formatter.general.fig_unit_height': 1 +} +style = IQXStandard(**my_style) + +# draw +draw(qc, style=style) +``` + +In the same way as above, you can create custom generator or layout functions and update existing stylesheet with custom functions. This feature enables you to control the most of appearance of the output image without modifying the codebase of the scheduled circuit drawer. + diff --git a/docs/api/qiskit/0.46/qiskit.visualization.visualize_transition.md b/docs/api/qiskit/0.46/qiskit.visualization.visualize_transition.md new file mode 100644 index 00000000000..c3746ef468d --- /dev/null +++ b/docs/api/qiskit/0.46/qiskit.visualization.visualize_transition.md @@ -0,0 +1,39 @@ +--- +title: visualize_transition +description: API reference for qiskit.visualization.visualize_transition +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit.visualization.visualize_transition +--- + + + +# qiskit.visualization.visualize\_transition + + + +`qiskit.visualization.visualize_transition(circuit, trace=False, saveas=None, fpg=100, spg=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/transition_visualization.py "view source code") + +Creates animation showing transitions between states of a single qubit by applying quantum gates. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – Qiskit single-qubit QuantumCircuit. Gates supported are h,x, y, z, rx, ry, rz, s, sdg, t, tdg and u1. +* **trace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Controls whether to display tracing vectors - history of 10 past vectors at each step of the animation. +* **saveas** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – User can choose to save the animation as a video to their filesystem. This argument is a string of path with filename and extension (e.g. “movie.mp4” to save the video in current working directory). +* **fpg** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Frames per gate. Finer control over animation smoothness and computational needs to render the animation. Works well for tkinter GUI as it is, for jupyter GUI it might be preferable to choose fpg between 5-30. +* **spg** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Seconds per gate. How many seconds should animation of individual gate transitions take. + +**Returns** + +If arg jupyter is set to True. Otherwise opens tkinter GUI and returns after the GUI is closed. + +**Return type** + +IPython.core.display.HTML + +**Raises** + +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – Must have Matplotlib (and/or IPython) installed. +* [**VisualizationError**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – Given gate(s) are not supported. + diff --git a/docs/api/qiskit/0.46/qobj.md b/docs/api/qiskit/0.46/qobj.md new file mode 100644 index 00000000000..8f12c528eb2 --- /dev/null +++ b/docs/api/qiskit/0.46/qobj.md @@ -0,0 +1,51 @@ +--- +title: qobj +description: API reference for qiskit.qobj +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.qobj +--- + + + + + + + +# Qobj + + + +`qiskit.qobj` + +## Base + +| | | +| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| [`QobjExperimentHeader`](qiskit.qobj.QobjExperimentHeader "qiskit.qobj.QobjExperimentHeader")(\*\*kwargs) | A class representing a header dictionary for a Qobj Experiment. | +| [`QobjHeader`](qiskit.qobj.QobjHeader "qiskit.qobj.QobjHeader")(\*\*kwargs) | A class used to represent a dictionary header in Qobj objects. | + +## Qasm + +| | | +| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [`QasmQobj`](qiskit.qobj.QasmQobj "qiskit.qobj.QasmQobj")(\[qobj\_id, config, experiments, header]) | An OpenQASM 2 Qobj. | +| [`QasmQobjInstruction`](qiskit.qobj.QasmQobjInstruction "qiskit.qobj.QasmQobjInstruction")(name\[, params, qubits, ...]) | A class representing a single instruction in an QasmQobj Experiment. | +| [`QasmQobjExperimentConfig`](qiskit.qobj.QasmQobjExperimentConfig "qiskit.qobj.QasmQobjExperimentConfig")(\[calibrations, ...]) | Configuration for a single OpenQASM 2 experiment in the qobj. | +| [`QasmQobjExperiment`](qiskit.qobj.QasmQobjExperiment "qiskit.qobj.QasmQobjExperiment")(\[config, header, ...]) | An OpenQASM 2 Qobj Experiment. | +| [`QasmQobjConfig`](qiskit.qobj.QasmQobjConfig "qiskit.qobj.QasmQobjConfig")(\[shots, seed\_simulator, ...]) | A configuration for an OpenQASM 2 Qobj. | +| [`QasmExperimentCalibrations`](qiskit.qobj.QasmExperimentCalibrations "qiskit.qobj.QasmExperimentCalibrations")(gates) | A container for any calibrations data. | +| [`GateCalibration`](qiskit.qobj.GateCalibration "qiskit.qobj.GateCalibration")(name, qubits, params, ...) | Each calibration specifies a unique gate by name, qubits and params, and contains the Pulse instructions to implement it. | + +## Pulse + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [`PulseQobj`](qiskit.qobj.PulseQobj "qiskit.qobj.PulseQobj")(qobj\_id, config, experiments\[, header]) | A Pulse Qobj. | +| [`PulseQobjInstruction`](qiskit.qobj.PulseQobjInstruction "qiskit.qobj.PulseQobjInstruction")(name, t0\[, ch, ...]) | A class representing a single instruction in an PulseQobj Experiment. | +| [`PulseQobjExperimentConfig`](qiskit.qobj.PulseQobjExperimentConfig "qiskit.qobj.PulseQobjExperimentConfig")(\[qubit\_lo\_freq, ...]) | A config for a single Pulse experiment in the qobj. | +| [`PulseQobjExperiment`](qiskit.qobj.PulseQobjExperiment "qiskit.qobj.PulseQobjExperiment")(instructions\[, config, ...]) | A Pulse Qobj Experiment. | +| [`PulseQobjConfig`](qiskit.qobj.PulseQobjConfig "qiskit.qobj.PulseQobjConfig")(meas\_level, meas\_return, ...) | A configuration for a Pulse Qobj. | +| [`QobjMeasurementOption`](qiskit.qobj.QobjMeasurementOption "qiskit.qobj.QobjMeasurementOption")(name\[, params]) | An individual measurement option. | +| [`PulseLibraryItem`](qiskit.qobj.PulseLibraryItem "qiskit.qobj.PulseLibraryItem")(name, samples) | An item in a pulse library. | + diff --git a/docs/api/qiskit/0.46/qpy.md b/docs/api/qiskit/0.46/qpy.md new file mode 100644 index 00000000000..066b775c41c --- /dev/null +++ b/docs/api/qiskit/0.46/qpy.md @@ -0,0 +1,1088 @@ +--- +title: qpy +description: API reference for qiskit.qpy +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.qpy +--- + + + + + + + +# QPY serialization + + + +`qiskit.qpy` + +QPY is a binary serialization format for [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") and [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") objects that is designed to be cross-platform, Python version agnostic, and backwards compatible moving forward. QPY should be used if you need a mechanism to save or copy between systems a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") that preserves the full Qiskit object structure (except for custom attributes defined outside of Qiskit code). This differs from other serialization formats like [OpenQASM](https://github.com/openqasm/openqasm) (2.0 or 3.0) which has a different abstraction model and can result in a loss of information contained in the original circuit (or is unable to represent some aspects of the Qiskit objects) or Python’s [pickle](https://docs.python.org/3/library/pickle.html) which will preserve the Qiskit object exactly but will only work for a single Qiskit version (it is also [potentially insecure](https://docs.python.org/3/library/pickle.html#module-pickle)). + +## Using QPY + +Using QPY is defined to be straightforward and mirror the user API of the serializers in Python’s standard library, `pickle` and `json`. There are 2 user facing functions: [`qiskit.qpy.dump()`](#qiskit.qpy.dump "qiskit.qpy.dump") and [`qiskit.qpy.load()`](#qiskit.qpy.load "qiskit.qpy.load") which are used to dump QPY data to a file object and load circuits from QPY data in a file object respectively. For example: + +```python +from qiskit.circuit import QuantumCircuit +from qiskit import qpy + +qc = QuantumCircuit(2, name='Bell', metadata={'test': True}) +qc.h(0) +qc.cx(0, 1) +qc.measure_all() + +with open('bell.qpy', 'wb') as fd: + qpy.dump(qc, fd) + +with open('bell.qpy', 'rb') as fd: + new_qc = qpy.load(fd)[0] +``` + +The [`qiskit.qpy.dump()`](#qiskit.qpy.dump "qiskit.qpy.dump") function also lets you include multiple circuits in a single QPY file: + +```python +with open('twenty_bells.qpy', 'wb') as fd: + qpy.dump([qc] * 20, fd) +``` + +and then loading that file will return a list with all the circuits + +> **with open(‘twenty\_bells.qpy’, ‘rb’) as fd:** +> +> twenty\_new\_bells = qpy.load(fd) + +### API documentation + +### load + + + +`qiskit.qpy.load(file_obj, metadata_deserializer=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qpy/interface.py "view source code") + +Load a QPY binary file + +This function is used to load a serialized QPY Qiskit program file and create [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") objects from its contents. For example: + +```python +from qiskit import qpy + +with open('bell.qpy', 'rb') as fd: + circuits = qpy.load(fd) +``` + +or with a gzip compressed file: + +```python +import gzip +from qiskit import qpy + +with gzip.open('bell.qpy.gz', 'rb') as fd: + circuits = qpy.load(fd) +``` + +which will read the contents of the qpy and return a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects or [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock") objects from the file. + +**Parameters** + +* **file\_obj** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.12)")) – A file like object that contains the QPY binary data for a circuit or pulse schedule. +* **metadata\_deserializer** ([*Type*](https://docs.python.org/3/library/typing.html#typing.Type "(in Python v3.12)")*\[JSONDecoder] | None*) – An optional JSONDecoder class that will be used for the `cls` kwarg on the internal `json.load` call used to deserialize the JSON payload used for the `.metadata` attribute for any programs in the QPY file. If this is not specified the circuit metadata will be parsed as JSON with the stdlib `json.load()` function using the default `JSONDecoder` class. + +**Returns** + +The list of Qiskit programs contained in the QPY data. A list is always returned, even if there is only 1 program in the QPY data. + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if `file_obj` is not a valid QPY file +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – When invalid data type is loaded. + +**Return type** + +[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")\[[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") | [*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")] + +### dump + + + +`qiskit.qpy.dump(programs, file_obj, metadata_serializer=None, use_symengine=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qpy/interface.py "view source code") + +Write QPY binary data to a file + +This function is used to save a circuit to a file for later use or transfer between machines. The QPY format is backwards compatible and can be loaded with future versions of Qiskit. + +For example: + +```python +from qiskit.circuit import QuantumCircuit +from qiskit import qpy + +qc = QuantumCircuit(2, name='Bell', metadata={'test': True}) +qc.h(0) +qc.cx(0, 1) +qc.measure_all() +``` + +from this you can write the qpy data to a file: + +```python +with open('bell.qpy', 'wb') as fd: + qpy.dump(qc, fd) +``` + +or a gzip compressed file: + +```python +import gzip + +with gzip.open('bell.qpy.gz', 'wb') as fd: + qpy.dump(qc, fd) +``` + +Which will save the qpy serialized circuit to the provided file. + +**Parameters** + +* **programs** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")*] |* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") *|*[*ScheduleBlock*](qiskit.pulse.ScheduleBlock "qiskit.pulse.schedule.ScheduleBlock")) – QPY supported object(s) to store in the specified file like object. QPY supports [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") and [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock"). Different data types must be separately serialized. +* **file\_obj** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.12)")) – The file like object to write the QPY data too +* **metadata\_serializer** ([*Type*](https://docs.python.org/3/library/typing.html#typing.Type "(in Python v3.12)")*\[JSONEncoder] | None*) – An optional JSONEncoder class that will be passed the `.metadata` attribute for each program in `programs` and will be used as the `cls` kwarg on the json.dump()\` call to JSON serialize that dictionary. +* **use\_symengine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, all objects containing symbolic expressions will be serialized using symengine’s native mechanism. This is a faster serialization alternative, but not supported in all platforms. Please check that your target platform is supported by the symengine library before setting this option, as it will be required by qpy to deserialize the payload. For this reason, the option defaults to False. + +**Raises** + +* [**QpyError**](#qiskit.qpy.QpyError "qiskit.qpy.QpyError") – When multiple data format is mixed in the output. +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – When invalid data type is input. + +These functions will raise a custom subclass of [`QiskitError`](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") if they encounter problems during serialization or deserialization. + +### QpyError + + + +`qiskit.qpy.QpyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/qpy/exceptions.py "view source code") + +Errors raised by the qpy module. + +Set the error message. + +### QPY Compatibility + +The QPY format is designed to be backwards compatible moving forward. This means you should be able to load a QPY with any newer Qiskit version than the one that generated it. However, loading a QPY file with an older Qiskit version is not supported and may not work. + +For example, if you generated a QPY file using qiskit-terra 0.18.1 you could load that QPY file with qiskit-terra 0.19.0 and a hypothetical qiskit-terra 0.29.0. However, loading that QPY file with 0.18.0 is not supported and may not work. + + + +## QPY Format + +The QPY serialization format is a portable cross-platform binary serialization format for [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects in Qiskit. The basic file format is as follows: + +A QPY file (or memory object) always starts with the following 6 byte UTF8 string: `QISKIT` which is immediately followed by the overall file header. The contents of the file header as defined as a C struct are: + +```python +struct { + uint8_t qpy_version; + uint8_t qiskit_major_version; + uint8_t qiskit_minor_version; + uint8_t qiskit_patch_version; + uint64_t num_circuits; +} +``` + +From V10 on, a new field is added to the file header struct to represent the encoding scheme used for symbolic expressions: + +```python +struct { + uint8_t qpy_version; + uint8_t qiskit_major_version; + uint8_t qiskit_minor_version; + uint8_t qiskit_patch_version; + uint64_t num_circuits; + char symbolic_encoding; +} +``` + +All values use network byte order [\[1\]](#f1) (big endian) for cross platform compatibility. + +The file header is immediately followed by the circuit payloads. Each individual circuit is composed of the following parts: + +`HEADER | METADATA | REGISTERS | CUSTOM_DEFINITIONS | INSTRUCTIONS` + +There is a circuit payload for each circuit (where the total number is dictated by `num_circuits` in the file header). There is no padding between the circuits in the data. + + + +### Version 10 + +Version 10 adds support for symengine-native serialization for objects of type [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") as well as symbolic expressions in Pulse schedule blocks. Version 10 also adds support for new fields in the [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") class added in the Qiskit 0.45.0 release. + +The symbolic\_encoding field is added to the file header, and a new encoding type char is introduced, mapped to each symbolic library as follows: `p` refers to sympy encoding and `e` refers to symengine encoding. + + + +#### FILE\_HEADER + +The contents of FILE\_HEADER after V10 are defined as a C struct as: + +```python +struct { + uint8_t qpy_version; + uint8_t qiskit_major_version; + uint8_t qiskit_minor_version; + uint8_t qiskit_patch_version; + uint64_t num_circuits; + char symbolic_encoding; +} +``` + +#### LAYOUT + +The `LAYOUT` struct is updated to have an additional `input_qubit_count` field. With version 10 the `LAYOUT` struct is now: + +```python +struct { + char exists; + int32_t initial_layout_size; + int32_t input_mapping_size; + int32_t final_layout_size; + uint32_t extra_registers; + int32_t input_qubit_count; +} +``` + +The rest of the layout data after the `LAYOUT` struct is represented as in previous versions. If `input qubit_count` is \< 0 that indicates that both `_input_qubit_count` and `_output_qubit_list` in the [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object are `None`. + + + +### Version 9 + +Version 9 adds support for classical [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") nodes and their associated [`Type`](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")s. + +#### EXPRESSION + +An [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") node is represented by a stream of variable-width data. A node itself is represented by (in order in the byte stream): + +1. a one-byte type code discriminator; +2. an EXPR\_TYPE object; +3. a type-code-specific additional payload; +4. a type-code-specific number of child EXPRESSION payloads (the number of these is implied by the type code and not explicitly stored). + +Each of these are described in the following table: + +| Qiskit class | Type code | Payload | Children | +| --------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") | `x` | One EXPR\_VAR. | 0 | +| [`Value`](circuit_classical#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") | `v` | One EXPR\_VALUE. | 0 | +| [`Cast`](circuit_classical#qiskit.circuit.classical.expr.Cast "qiskit.circuit.classical.expr.Cast") | `c` | One `_Bool` that corresponds to the value of `implicit`. | 1 | +| [`Unary`](circuit_classical#qiskit.circuit.classical.expr.Unary "qiskit.circuit.classical.expr.Unary") | `u` | One `uint8_t` with the same numeric value as the [`Unary.Op`](circuit_classical#qiskit.circuit.classical.expr.Unary.Op "qiskit.circuit.classical.expr.Unary.Op"). | 1 | +| [`Binary`](circuit_classical#qiskit.circuit.classical.expr.Binary "qiskit.circuit.classical.expr.Binary") | `b` | One `uint8_t` with the same numeric value as the [`Binary.Op`](circuit_classical#qiskit.circuit.classical.expr.Binary.Op "qiskit.circuit.classical.expr.Binary.Op"). | 2 | + + + +#### EXPR\_TYPE + +A [`Type`](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type") is encoded by a single-byte ASCII `char` that encodes the kind of type, followed by a payload that varies depending on the type. The defined codes are: + +| Qiskit class | Type code | Payload | +| ----------------------------------------------------------------------------------------------------- | --------- | --------------------- | +| [`Bool`](circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool") | `b` | None. | +| [`Uint`](circuit_classical#qiskit.circuit.classical.types.Uint "qiskit.circuit.classical.types.Uint") | `u` | One `uint32_t width`. | + + + +#### EXPR\_VAR + +This represents a runtime variable of a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node. These are a type code, followed by a type-code-specific payload: + +| Python class | Type code | Payload | +| ------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | +| [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") | `C` | One `uint32_t index` that is the index of the [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") in the containing circuit. | +| [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") | `R` | One `uint16_t reg_name_size`, followed by that many bytes of UTF-8 string data of the register name. | + + + +#### EXPR\_VALUE + +This represents a literal object in the classical type system, such as an integer. Currently there are very few such literals. These are encoded as a type code, followed by a type-code-specific payload. + +| Python type | Type code | Payload | +| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `bool` | `b` | One `_Bool value`. | +| `int` | `i` | One `uint8_t num_bytes`, followed by the integer encoded into that many many bytes (network order) in a two’s complement representation. | + +#### Changes to INSTRUCTION + +To support the use of [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") nodes in the fields [`IfElseOp.condition`](qiskit.circuit.IfElseOp#condition "qiskit.circuit.IfElseOp.condition"), [`WhileLoopOp.condition`](qiskit.circuit.WhileLoopOp#condition "qiskit.circuit.WhileLoopOp.condition") and `SwitchCaseOp.target`, the INSTRUCTION struct is changed in an ABI compatible-manner to [its previous definition](#qpy-instruction-v5). The new struct is the C struct: + +```python +struct { + uint16_t name_size; + uint16_t label_size; + uint16_t num_parameters; + uint32_t num_qargs; + uint32_t num_cargs; + uint8_t conditional_key; + uint16_t conditional_reg_name_size; + int64_t conditional_value; + uint32_t num_ctrl_qubits; + uint32_t ctrl_state; +} +``` + +where the only change is that a `uint8_t conditional_key` entry has replaced `_Bool has_conditional`. This new `conditional_key` takes the following numeric values, with these effects: + +| Value | Effects | +| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0 | The instruction has its `.condition` field set to `None`. The `conditional_reg_name_size` and `conditional_value` fields should be ignored. | +| 1 | The instruction has its `.condition` field set to a 2-tuple of either a [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") or a [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister"), and a integer of value `conditional_value`. The INSTRUCTION payload, including its trailing data is parsed exactly as it would be in QPY versions less than 8. | +| 2 | The instruction has its `.condition` field set to a [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") node. The `conditional_reg_name_size` and `conditional_value` fields should be ignored. The data following the struct is followed (as in QPY versions less than 8) by `name_size` bytes of UTF-8 string data for the class name and `label_size` bytes of UTF-8 string data for the label (if any). Then, there is one INSTRUCTION\_PARAM, which will contain an EXPRESSION. After that, parsing continues with the INSTRUCTION\_ARG structs, as in previous versions of QPY. | + + + +#### Changes to INSTRUCTION\_PARAM + +A new type code `x` is added that defines an EXPRESSION parameter. + + + +### Version 8 + +Version 8 adds support for handling a [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") stored in the [`QuantumCircuit.layout`](qiskit.circuit.QuantumCircuit#layout "qiskit.circuit.QuantumCircuit.layout") attribute. In version 8 immediately following the calibrations block at the end of the circuit payload there is now the `LAYOUT` struct. This struct outlines the size of the three attributes of a [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") class. + + + +#### LAYOUT + +```python +struct { + char exists; + int32_t initial_layout_size; + int32_t input_mapping_size; + int32_t final_layout_size; + uint32_t extra_registers; +} +``` + +If any of the signed values are `-1` this indicates the corresponding attribute is `None`. + +Immediately following the `LAYOUT` struct there is a [REGISTERS](#qpy-registers) struct for `extra_registers` (specifically the format introduced in [Version 4](#qpy-version-4)) standalone register definitions that aren’t present in the circuit. Then there are `initial_layout_size` `INITIAL_LAYOUT_BIT` structs to define the [`TranspileLayout.initial_layout`](qiskit.transpiler.TranspileLayout#initial_layout "qiskit.transpiler.TranspileLayout.initial_layout") attribute. + + + +#### INITIAL\_LAYOUT\_BIT + +```python +struct { + int32_t index; + int32_t register_size; +} +``` + +Where a value of `-1` indicates `None` (as in no register is associated with the bit). Following each `INITIAL_LAYOUT_BIT` struct is `register_size` bytes for a `utf8` encoded string for the register name. + +Following the initial layout there is `input_mapping_size` array of `uint32_t` integers representing the positions of the physical bit from the initial layout. This enables constructing a list of virtual bits where the array index is its input mapping position. + +Finally, there is an array of `final_layout_size` `uint32_t` integers. Each element is an index in the circuit’s `qubits` attribute which enables building a mapping from qubit starting position to the output position at the end of the circuit. + + + +### Version 7 + +Version 7 adds support for `Reference` instruction and serialization of a `ScheduleBlock` program while keeping its reference to subroutines: + +```python +from qiskit import pulse +from qiskit import qpy + +with pulse.build() as schedule: + pulse.reference("cr45p", "q0", "q1") + pulse.reference("x", "q0") + pulse.reference("cr45p", "q0", "q1") + +with open('template_ecr.qpy', 'wb') as fd: + qpy.dump(schedule, fd) +``` + +The conventional [SCHEDULE\_BLOCK](#qpy-schedule-block) data model is preserved, but in version 7 it is immediately followed by an extra [MAPPING](#qpy-mapping) utf8 bytes block representing the data of the referenced subroutines. + +New type key character is added to the [SCHEDULE\_BLOCK\_INSTRUCTIONS](#qpy-schedule-instructions) group for the `Reference` instruction. + +* `y`: [`Reference`](qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference") instruction + +New type key character is added to the [SCHEDULE\_BLOCK\_OPERANDS](#qpy-schedule-operands) group for the operands of `Reference` instruction, which is a tuple of strings, e.g. (“cr45p”, “q0”, “q1”). + +* `o`: string (operand string) + +Note that this is the same encoding with the built-in Python string, however, the standard value encoding in QPY uses `s` type character for string data, which conflicts with the [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") in the scope of pulse instruction operands. A special type character `o` is reserved for the string data that appears in the pulse instruction operands. + +In addition, version 7 adds two new type keys to the INSTRUCTION\_PARM struct. `"d"` is followed by no data and represents the literal value [`CASE_DEFAULT`](circuit#qiskit.circuit.CASE_DEFAULT "qiskit.circuit.CASE_DEFAULT") for switch-statement support. `"R"` represents a [`ClassicalRegister`](qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") or [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit"), and is followed by the same format as the description of register or classical bit as used in the first element of [the condition of an INSTRUCTION field](#qpy-instructions). + + + +### Version 6 + +Version 6 adds support for `ScalableSymbolicPulse`. These objects are saved and read like SymbolicPulse objects, and the class name is added to the data to correctly handle the class selection. + +SymbolicPulse block now starts with SYMBOLIC\_PULSE\_V2 header: + +```python +struct { + uint16_t class_name_size; + uint16_t type_size; + uint16_t envelope_size; + uint16_t constraints_size; + uint16_t valid_amp_conditions_size; + _bool amp_limited; +} +``` + +The only change compared to [Version 5](#qpy-version-5) is the addition of class\_name\_size. The header is then immediately followed by `class_name_size` utf8 bytes with the name of the class. Currently, either SymbolicPulse or ScalableSymbolicPulse are supported. The rest of the data is then identical to [Version 5](#qpy-version-5). + + + +### Version 5 + +Version 5 changes from [Version 4](#qpy-version-4) by adding support for `ScheduleBlock` and changing two payloads the INSTRUCTION metadata payload and the CUSTOM\_INSTRUCTION block. These now have new fields to better account for [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") objects in a circuit. In addition, new payload MAP\_ITEM is defined to implement the [MAPPING](#qpy-mapping) block. + +With the support of `ScheduleBlock`, now [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") can be serialized together with [`calibrations`](qiskit.circuit.QuantumCircuit#calibrations "qiskit.circuit.QuantumCircuit.calibrations"), or [Pulse Gates](https://docs.quantum-computing.ibm.com/build/pulse). In QPY version 5 and above, [CIRCUIT\_CALIBRATIONS](#qpy-circuit-calibrations) payload is packed after the [INSTRUCTIONS](#qpy-instructions) block. + +In QPY version 5 and above, + +```python +struct { + char type; +} +``` + +immediately follows the file header block to represent the program type stored in the file. + +* When `type==c`, [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") payload follows +* When `type==s`, [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") payload follows + + + Different programs cannot be packed together in the same file. You must create different files for different program types. Multiple objects with the same type can be saved in a single file. + + + + + + +#### SCHEDULE\_BLOCK + +[`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") is first supported in QPY Version 5. This allows users to save pulse programs in the QPY binary format as follows: + +```python +from qiskit import pulse, qpy + +with pulse.build() as schedule: + pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0)) + +with open('schedule.qpy', 'wb') as fd: + qpy.dump(qc, fd) + +with open('schedule.qpy', 'rb') as fd: + new_qc = qpy.load(fd)[0] +``` + +Note that circuit and schedule block are serialized and deserialized through the same QPY interface. Input data type is implicitly analyzed and no extra option is required to save the schedule block. + + + + + +#### SCHEDULE\_BLOCK\_HEADER + +[`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") block starts with the following header: + +```python +struct { + uint16_t name_size; + uint64_t metadata_size; + uint16_t num_element; +} +``` + +which is immediately followed by `name_size` utf8 bytes of schedule name and `metadata_size` utf8 bytes of the JSON serialized metadata dictionary attached to the schedule. + + + + + +#### SCHEDULE\_BLOCK\_ALIGNMENTS + +Then, alignment context of the schedule block starts with `char` representing the supported context type followed by the [SEQUENCE](#qpy-sequence) block representing the parameters associated with the alignment context `AlignmentKind._context_params`. The context type char is mapped to each alignment subclass as follows: + +* `l`: [`AlignLeft`](qiskit.pulse.transforms.AlignLeft "qiskit.pulse.transforms.AlignLeft") +* `r`: [`AlignRight`](qiskit.pulse.transforms.AlignRight "qiskit.pulse.transforms.AlignRight") +* `s`: [`AlignSequential`](qiskit.pulse.transforms.AlignSequential "qiskit.pulse.transforms.AlignSequential") +* `e`: [`AlignEquispaced`](qiskit.pulse.transforms.AlignEquispaced "qiskit.pulse.transforms.AlignEquispaced") + +Note that [`AlignFunc`](qiskit.pulse.transforms.AlignFunc "qiskit.pulse.transforms.AlignFunc") context is not supported because of the callback function stored in the context parameters. + + + + + +#### SCHEDULE\_BLOCK\_INSTRUCTIONS + +This alignment block is further followed by `num_element` length of block elements which may consist of nested schedule blocks and schedule instructions. Each schedule instruction starts with `char` representing the instruction type followed by the [SEQUENCE](#qpy-sequence) block representing the instruction `operands`. Note that the data structure of pulse [`Instruction`](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.Instruction") is unified so that instance can be uniquely determined by the class and a tuple of operands. The mapping of type char to the instruction subclass is defined as follows: + +* `a`: [`Acquire`](qiskit.pulse.instructions.Acquire "qiskit.pulse.instructions.Acquire") instruction +* `p`: [`Play`](qiskit.pulse.instructions.Play "qiskit.pulse.instructions.Play") instruction +* `d`: [`Delay`](qiskit.pulse.instructions.Delay "qiskit.pulse.instructions.Delay") instruction +* `f`: [`SetFrequency`](qiskit.pulse.instructions.SetFrequency "qiskit.pulse.instructions.SetFrequency") instruction +* `g`: [`ShiftFrequency`](qiskit.pulse.instructions.ShiftFrequency "qiskit.pulse.instructions.ShiftFrequency") instruction +* `q`: [`SetPhase`](qiskit.pulse.instructions.SetPhase "qiskit.pulse.instructions.SetPhase") instruction +* `r`: [`ShiftPhase`](qiskit.pulse.instructions.ShiftPhase "qiskit.pulse.instructions.ShiftPhase") instruction +* `b`: [`RelativeBarrier`](qiskit.pulse.instructions.RelativeBarrier "qiskit.pulse.instructions.RelativeBarrier") instruction +* `t`: [`TimeBlockade`](qiskit.pulse.instructions.TimeBlockade "qiskit.pulse.instructions.TimeBlockade") instruction +* `y`: [`Reference`](qiskit.pulse.instructions.Reference "qiskit.pulse.instructions.Reference") instruction (new in version 0.7) + + + + + +#### SCHEDULE\_BLOCK\_OPERANDS + +The operands of these instances can be serialized through the standard QPY value serialization mechanism, however there are special object types that only appear in the schedule operands. Since the operands are serialized as [SEQUENCE](#qpy-sequence), each element must be packed with the INSTRUCTION\_PARAM pack struct, where each payload starts with a header block consists of the char `type` and uint64\_t `size`. Special objects start with the following type key: + +* `c`: [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") +* `w`: [`Waveform`](qiskit.pulse.library.Waveform "qiskit.pulse.library.Waveform") +* `s`: [`SymbolicPulse`](qiskit.pulse.library.SymbolicPulse "qiskit.pulse.library.SymbolicPulse") +* `o`: string (operand string, new in version 0.7) + + + +#### CHANNEL + +Channel block starts with channel subtype `char` that maps an object data to [`Channel`](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel") subclass. Mapping is defined as follows: + +* `d`: [`DriveChannel`](qiskit.pulse.channels.DriveChannel "qiskit.pulse.channels.DriveChannel") +* `c`: [`ControlChannel`](qiskit.pulse.channels.ControlChannel "qiskit.pulse.channels.ControlChannel") +* `m`: [`MeasureChannel`](qiskit.pulse.channels.MeasureChannel "qiskit.pulse.channels.MeasureChannel") +* `a`: [`AcquireChannel`](qiskit.pulse.channels.AcquireChannel "qiskit.pulse.channels.AcquireChannel") +* `e`: [`MemorySlot`](qiskit.pulse.channels.MemorySlot "qiskit.pulse.channels.MemorySlot") +* `r`: [`RegisterSlot`](qiskit.pulse.channels.RegisterSlot "qiskit.pulse.channels.RegisterSlot") + +The key is immediately followed by the channel index serialized as the INSTRUCTION\_PARAM. + + + +#### Waveform + +Waveform block starts with WAVEFORM header: + +```python +struct { + double epsilon; + uint32_t data_size; + _bool amp_limited; +} +``` + +which is followed by `data_size` bytes of complex `ndarray` binary generated by [numpy.save](https://numpy.org/doc/stable/reference/generated/numpy.save.html). This represents the complex IQ data points played on a quantum device. [`name`](qiskit.pulse.library.Waveform#name "qiskit.pulse.library.Waveform.name") is saved after the samples in the INSTRUCTION\_PARAM pack struct, which can be string or `None`. + + + +#### SymbolicPulse + +SymbolicPulse block starts with SYMBOLIC\_PULSE header: + +```python +struct { + uint16_t type_size; + uint16_t envelope_size; + uint16_t constraints_size; + uint16_t valid_amp_conditions_size; + _bool amp_limited; +} +``` + +which is followed by `type_size` utf8 bytes of [`SymbolicPulse.pulse_type`](qiskit.pulse.library.SymbolicPulse#pulse_type "qiskit.pulse.library.SymbolicPulse.pulse_type") string that represents a class of waveform, such as “Gaussian” or “GaussianSquare”. Then, `envelope_size`, `constraints_size`, `valid_amp_conditions_size` utf8 bytes of serialized symbolic expressions are generated for [`SymbolicPulse.envelope`](qiskit.pulse.library.SymbolicPulse#envelope "qiskit.pulse.library.SymbolicPulse.envelope"), [`SymbolicPulse.constraints`](qiskit.pulse.library.SymbolicPulse#constraints "qiskit.pulse.library.SymbolicPulse.constraints"), and [`SymbolicPulse.valid_amp_conditions`](qiskit.pulse.library.SymbolicPulse#valid_amp_conditions "qiskit.pulse.library.SymbolicPulse.valid_amp_conditions"), respectively. Since string representation of these expressions are usually lengthy, the expression binary is generated by the python [zlib](https://docs.python.org/3/library/zlib.html) module with data compression. + +To uniquely specify a pulse instance, we also need to store the associated parameters, which consist of `duration` and the rest of parameters as a dictionary. Dictionary parameters are first dumped in the [MAPPING](#qpy-mapping) form, and then `duration` is dumped with the INSTRUCTION\_PARAM pack struct. Lastly, [`name`](qiskit.pulse.library.SymbolicPulse#name "qiskit.pulse.library.SymbolicPulse.name") is saved also with the INSTRUCTION\_PARAM pack struct, which can be string or `None`. + + + +#### MAPPING + +The MAPPING is a representation for arbitrary mapping object. This is a fixed length [SEQUENCE](#qpy-sequence) of key-value pair represented by the MAP\_ITEM payload. + +A MAP\_ITEM starts with a header defined as: + +```python +struct { + uint16_t key_size; + char type; + uint16_t size; +} +``` + +which is immediately followed by the `key_size` utf8 bytes representing the dictionary key in string and `size` utf8 bytes of arbitrary object data of QPY serializable `type`. + + + + + +#### CIRCUIT\_CALIBRATIONS + +The CIRCUIT\_CALIBRATIONS block is a dictionary to define pulse calibrations of the custom instruction set. This block starts with the following CALIBRATION header: + +```python +struct { + uint16_t num_cals; +} +``` + +which is followed by the `num_cals` length of calibration entries, each starts with the CALIBRATION\_DEF header: + +```python +struct { + uint16_t name_size; + uint16_t num_qubits; + uint16_t num_params; + char type; +} +``` + +The calibration definition header is then followed by `name_size` utf8 bytes of the gate name, `num_qubits` length of integers representing a sequence of qubits, and `num_params` length of INSTRUCTION\_PARAM payload for parameters associated to the custom instruction. The `type` indicates the class of pulse program which is either, in principle, [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") or [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule"). As of QPY Version 5, only [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") payload is supported. Finally, [SCHEDULE\_BLOCK](#qpy-schedule-block) payload is packed for each CALIBRATION\_DEF entry. + + + +#### INSTRUCTION + +The INSTRUCTION block was modified to add two new fields `num_ctrl_qubits` and `ctrl_state` which are used to model the [`ControlledGate.num_ctrl_qubits`](qiskit.circuit.ControlledGate#num_ctrl_qubits "qiskit.circuit.ControlledGate.num_ctrl_qubits") and [`ControlledGate.ctrl_state`](qiskit.circuit.ControlledGate#ctrl_state "qiskit.circuit.ControlledGate.ctrl_state") attributes. The new payload packed struct format is: + +```python +struct { + uint16_t name_size; + uint16_t label_size; + uint16_t num_parameters; + uint32_t num_qargs; + uint32_t num_cargs; + _Bool has_conditional; + uint16_t conditional_reg_name_size; + int64_t conditional_value; + uint32_t num_ctrl_qubits; + uint32_t ctrl_state; +} +``` + +The rest of the instruction payload is the same. You can refer to [INSTRUCTIONS](#qpy-instructions) for the details of the full payload. + + + +#### CUSTOM\_INSTRUCTION + +The CUSTOM\_INSTRUCTION block in QPY version 5 adds a new field `base_gate_size` which is used to define the size of the [`qiskit.circuit.Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object stored in the `ControlledGate.base_gate` attribute for a custom [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") object. With this change the CUSTOM\_INSTRUCTION metadata block becomes: + +```python +struct { + uint16_t name_size; + char type; + uint32_t num_qubits; + uint32_t num_clbits; + _Bool custom_definition; + uint64_t size; + uint32_t num_ctrl_qubits; + uint32_t ctrl_state; + uint64_t base_gate_size +} +``` + +Immediately following the CUSTOM\_INSTRUCTION struct is the utf8 encoded name of size `name_size`. + +If `custom_definition` is `True` that means that the immediately following `size` bytes contains a QPY circuit data which can be used for the custom definition of that gate. If `custom_definition` is `False` then the instruction can be considered opaque (ie no definition). The `type` field determines what type of object will get created with the custom definition. If it’s `'g'` it will be a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object, `'i'` it will be a [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object. + +Following this the next `base_gate_size` bytes contain the `INSTRUCTION` payload for the `ControlledGate.base_gate`. + +Additionally an addition value for `type` is added `'c'` which is used to indicate the custom instruction is a custom [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate"). + + + +### Version 4 + +Version 4 is identical to [Version 3](#qpy-version-3) except that it adds 2 new type strings to the INSTRUCTION\_PARAM struct, `z` to represent `None` (which is encoded as no data), `q` to represent a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") (which is encoded as a QPY circuit), `r` to represent a `range` of integers (which is encoded as a [RANGE](#qpy-range-pack)), and `t` to represent a `sequence` (which is encoded as defined by [SEQUENCE](#qpy-sequence)). Additionally, version 4 changes the type of register index mapping array from `uint32_t` to `int64_t`. If the values of any of the array elements are negative they represent a register bit that is not present in the circuit. + +The [REGISTERS](#qpy-registers) header format has also been updated to + +```python +struct { + char type; + _Bool standalone; + uint32_t size; + uint16_t name_size; + _bool in_circuit; +} +``` + +which just adds the `in_circuit` field which represents whether the register is part of the circuit or not. + + + +#### RANGE + +A RANGE is a representation of a `range` object. It is defined as: + +```python +struct { + int64_t start; + int64_t stop; + int64_t step; +} +``` + + + +#### SEQUENCE + +A SEQUENCE is a representation of an arbitrary sequence object. As sequence are just fixed length containers of arbitrary python objects their QPY can’t fully represent any sequence, but as long as the contents in a sequence are other QPY serializable types for the INSTRUCTION\_PARAM payload the `sequence` object can be serialized. + +A sequence instruction parameter starts with a header defined as: + +```python +struct { + uint64_t size; +} +``` + +followed by `size` elements that are INSTRUCTION\_PARAM payloads, where each of these define an element in the sequence. The sequence object will be typecasted into proper type, e.g. `tuple`, afterwards. + + + +### Version 3 + +Version 3 of the QPY format is identical to [Version 2](#qpy-version-2) except that it defines a struct format to represent a [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate") natively in QPY. To accomplish this the [CUSTOM\_DEFINITIONS](#qpy-custom-definition) struct now supports a new type value `'p'` to represent a [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate"). Enties in the custom instructions tables have unique name generated that start with the string `"###PauliEvolutionGate_"` followed by a uuid string. This gate name is reservered in QPY and if you have a custom [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object with a definition set and that name prefix it will error. If it’s of type `'p'` the data payload is defined as follows: + + + + + +#### PAULI\_EVOLUTION + +This represents the high level [`PauliEvolutionGate`](qiskit.circuit.library.PauliEvolutionGate "qiskit.circuit.library.PauliEvolutionGate") + +```python +struct { + uint64_t operator_count; + _Bool standalone_op; + char time_type; + uint64_t time_size; + uint64_t synthesis_size; +} +``` + +This is immediately followed by `operator_count` elements defined by the [SPARSE\_PAULI\_OP\_LIST\_ELEM](#qpy-pauli-sum-op) payload. Following that we have `time_size` bytes representing the `time` attribute. If `standalone_op` is `True` then there must only be a single operator. The encoding of these bytes is determined by the value of `time_type`. Possible values of `time_type` are `'f'`, `'p'`, and `'e'`. If `time_type` is `'f'` it’s a double, `'p'` defines a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") object which is represented by a [PARAMETER](#qpy-param-struct), `e` defines a [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") object (that’s not a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")) which is represented by a [PARAMETER\_EXPR](#qpy-param-expr). Following that is `synthesis_size` bytes which is a utf8 encoded json payload representing the [`EvolutionSynthesis`](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis") class used by the gate. + + + + + +#### SPARSE\_PAULI\_OP\_LIST\_ELEM + +This represents an instance of [`PauliSumOp`](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp"). + +```python +struct { + uint32_t pauli_op_size; +} +``` + +which is immediately followed by `pauli_op_size` bytes which are .npy format [\[2\]](#f2) data which represents the [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"). + +Version 3 of the QPY format also defines a struct format to represent a `ParameterVectorElement` as a distinct subclass from a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter"). This adds a new parameter type char `'v'` to represent a `ParameterVectorElement` which is now supported as a type string value for an INSTRUCTION\_PARAM. The payload for these parameters are defined below as [PARAMETER\_VECTOR\_ELEMENT](#qpy-param-vector). + + + + + +#### PARAMETER\_VECTOR\_ELEMENT + +A PARAMETER\_VECTOR\_ELEMENT represents a `ParameterVectorElement` object the data for a INSTRUCTION\_PARAM. The contents of the PARAMETER\_VECTOR\_ELEMENT are defined as: + +```python +struct { + uint16_t vector_name_size; + uint64_t vector_size; + char uuid[16]; + uint64_t index; +} +``` + +which is immediately followed by `vector_name_size` utf8 bytes representing the parameter’s vector name. + + + + + +#### PARAMETER\_EXPR + +Additionally, since QPY format version v3 distinguishes between a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") and `ParameterVectorElement` the payload for a [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") needs to be updated to distinguish between the types. The following is the modified payload format which is mostly identical to the format in Version 1 and [Version 2](#qpy-version-2) but just modifies the `map_elements` struct to include a symbol type field. + +A PARAMETER\_EXPR represents a [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") object that the data for an INSTRUCTION\_PARAM. The contents of a PARAMETER\_EXPR are defined as: + +```python +struct { + uint64_t map_elements; + uint64_t expr_size; +} +``` + +Immediately following the header is `expr_size` bytes of utf8 data containing the expression string, which is the sympy srepr of the expression for the parameter expression. Following that is a symbol map which contains `map_elements` elements with the format + +```python +struct { + char symbol_type; + char type; + uint64_t size; +} +``` + +The `symbol_type` key determines the payload type of the symbol representation for the element. If it’s `p` it represents a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") and if it’s `v` it represents a `ParameterVectorElement`. The map element struct is immediately followed by the symbol map key payload, if `symbol_type` is `p` then it is followed immediately by a [PARAMETER](#qpy-param-struct) object (both the struct and utf8 name bytes) and if `symbol_type` is `v` then the struct is imediately followed by [PARAMETER\_VECTOR\_ELEMENT](#qpy-param-vector) (both the struct and utf8 name bytes). That is followed by `size` bytes for the data of the symbol. The data format is dependent on the value of `type`. If `type` is `p` then it represents a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") and size will be 0, the value will just be the same as the key. Similarly if the `type` is `v` then it represents a `ParameterVectorElement` and size will be 0 as the value will just be the same as the key. If `type` is `f` then it represents a double precision float. If `type` is `c` it represents a double precision complex, which is represented by the [COMPLEX](#qpy-complex). Finally, if type is `i` it represents an integer which is an `int64_t`. + + + +### Version 2 + +Version 2 of the QPY format is identical to version 1 except for the HEADER section is slightly different. You can refer to the [Version 1](#qpy-version-1) section for the details on the rest of the payload format. + +#### HEADER + +The contents of HEADER are defined as a C struct are: + +```python +struct { + uint16_t name_size; + char global_phase_type; + uint16_t global_phase_size; + uint32_t num_qubits; + uint32_t num_clbits; + uint64_t metadata_size; + uint32_t num_registers; + uint64_t num_instructions; + uint64_t num_custom_gates; +} +``` + +This is immediately followed by `name_size` bytes of utf8 data for the name of the circuit. Following this is immediately `global_phase_size` bytes representing the global phase. The content of that data is dictated by the value of `global_phase_type`. If it’s `'f'` the data is a float and is the size of a `double`. If it’s `'p'` defines a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") object which is represented by a PARAM struct (see below), `e` defines a [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") object (that’s not a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")) which is represented by a PARAM\_EXPR struct (see below). + + + +### Version 1 + + + +#### HEADER + +The contents of HEADER as defined as a C struct are: + +```python +struct { + uint16_t name_size; + double global_phase; + uint32_t num_qubits; + uint32_t num_clbits; + uint64_t metadata_size; + uint32_t num_registers; + uint64_t num_instructions; + uint64_t num_custom_gates; +} +``` + +This is immediately followed by `name_size` bytes of utf8 data for the name of the circuit. + +#### METADATA + +The METADATA field is a UTF8 encoded JSON string. After reading the HEADER (which is a fixed size at the start of the QPY file) and the `name` string you then read the `metadata_size` number of bytes and parse the JSON to get the metadata for the circuit. + + + +#### REGISTERS + +The contents of REGISTERS is a number of REGISTER object. If num\_registers is > 0 then after reading METADATA you read that number of REGISTER structs defined as: + +```python +struct { + char type; + _Bool standalone; + uint32_t size; + uint16_t name_size; +} +``` + +`type` can be `'q'` or `'c'`. + +Immediately following the REGISTER struct is the utf8 encoded register name of size `name_size`. After the `name` utf8 bytes there is then an array of int64\_t values of size `size` that contains a map of the register’s index to the circuit’s qubit index. For example, array element 0’s value is the index of the `register[0]`’s position in the containing circuit’s qubits list. + + + Prior to QPY [Version 4](#qpy-version-4) the type of array elements was uint32\_t. This was changed to enable negative values which represent bits in the array not present in the circuit + + +The standalone boolean determines whether the register is constructed as a standalone register that was added to the circuit or was created from existing bits. A register is considered standalone if it has bits constructed solely as part of it, for example: + +```python +qr = QuantumRegister(2) +qc = QuantumCircuit(qr) +``` + +the register `qr` would be a standalone register. While something like: + +```python +bits = [Qubit(), Qubit()] +qr2 = QuantumRegister(bits=bits) +qc = QuantumCircuit(qr2) +``` + +`qr2` would have `standalone` set to `False`. + + + + + +#### CUSTOM\_DEFINITIONS + +This section specifies custom definitions for any of the instructions in the circuit. + +CUSTOM\_DEFINITION\_HEADER contents are defined as: + +```python +struct { + uint64_t size; +} +``` + +If size is greater than 0 that means the circuit contains custom instruction(s). Each custom instruction is defined with a CUSTOM\_INSTRUCTION block defined as: + +```python +struct { + uint16_t name_size; + char type; + uint32_t num_qubits; + uint32_t num_clbits; + _Bool custom_definition; + uint64_t size; +} +``` + +Immediately following the CUSTOM\_INSTRUCTION struct is the utf8 encoded name of size `name_size`. + +If `custom_definition` is `True` that means that the immediately following `size` bytes contains a QPY circuit data which can be used for the custom definition of that gate. If `custom_definition` is `False` then the instruction can be considered opaque (ie no definition). The `type` field determines what type of object will get created with the custom definition. If it’s `'g'` it will be a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") object, `'i'` it will be a [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") object. + + + +#### INSTRUCTIONS + +The contents of INSTRUCTIONS is a list of INSTRUCTION metadata objects + +```python +struct { + uint16_t name_size; + uint16_t label_size; + uint16_t num_parameters; + uint32_t num_qargs; + uint32_t num_cargs; + _Bool has_conditional; + uint16_t conditional_reg_name_size; + int64_t conditional_value; +} +``` + +This metadata object is immediately followed by `name_size` bytes of utf8 bytes for the `name`. `name` here is the Qiskit class name for the Instruction class if it’s defined in Qiskit. Otherwise it falls back to the custom instruction name. Following the `name` bytes there are `label_size` bytes of utf8 data for the label if one was set on the instruction. Following the label bytes if `has_conditional` is `True` then there are `conditional_reg_name_size` bytes of utf8 data for the name of the conditional register name. In case of single classical bit conditions the register name utf8 data will be prefixed with a null character “x00” and then a utf8 string integer representing the classical bit index in the circuit that the condition is on. + +This is immediately followed by the INSTRUCTION\_ARG structs for the list of arguments of that instruction. These are in the order of all quantum arguments (there are num\_qargs of these) followed by all classical arguments (num\_cargs of these). + +The contents of each INSTRUCTION\_ARG is: + +```python +struct { + char type; + uint32_t index; +} +``` + +`type` can be `'q'` or `'c'`. + +After all arguments for an instruction the parameters are specified with `num_parameters` INSTRUCTION\_PARAM structs. + +The contents of each INSTRUCTION\_PARAM is: + +```python +struct { + char type; + uint64_t size; +} +``` + +After each INSTRUCTION\_PARAM the next `size` bytes are the parameter’s data. The `type` field can be `'i'`, `'f'`, `'p'`, `'e'`, `'s'`, `'c'` or `'n'` which dictate the format. For `'i'` it’s an integer, `'f'` it’s a double, `'s'` if it’s a string (encoded as utf8), `'c'` is a complex and the data is represented by the struct format in the [PARAMETER\_EXPR](#qpy-param-expr) section. `'p'` defines a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") object which is represented by a [PARAMETER](#qpy-param-struct) struct, `e` defines a [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") object (that’s not a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")) which is represented by a [PARAMETER\_EXPR](#qpy-param-expr) struct (on QPY format [Version 3](#qpy-version-3) the format is tweak slightly see: [PARAMETER\_EXPR](#qpy-param-expr-v3)), `'n'` represents an object from numpy (either an `ndarray` or a numpy type) which means the data is .npy format [\[2\]](#f2) data, and in QPY [Version 3](#qpy-version-3) `'v'` represents a `ParameterVectorElement` which is represented by a [PARAMETER\_VECTOR\_ELEMENT](#qpy-param-vector) struct. + + + +#### PARAMETER + +A PARAMETER represents a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") object the data for a INSTRUCTION\_PARAM. The contents of the PARAMETER are defined as: + +```python +struct { + uint16_t name_size; + char uuid[16]; +} +``` + +which is immediately followed by `name_size` utf8 bytes representing the parameter name. + + + + + +#### PARAMETER\_EXPR + +A PARAMETER\_EXPR represents a [`ParameterExpression`](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") object that the data for an INSTRUCTION\_PARAM. The contents of a PARAMETER\_EXPR are defined as: + +The PARAMETER\_EXPR data starts with a header: + +```python +struct { + uint64_t map_elements; + uint64_t expr_size; +} +``` + +Immediately following the header is `expr_size` bytes of utf8 data containing the expression string, which is the sympy srepr of the expression for the parameter expression. Follwing that is a symbol map which contains `map_elements` elements with the format + +```python +struct { + char type; + uint64_t size; +} +``` + +Which is followed immediately by `PARAMETER` object (both the struct and utf8 name bytes) for the symbol map key. That is followed by `size` bytes for the data of the symbol. The data format is dependent on the value of `type`. If `type` is `p` then it represents a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") and size will be 0, the value will just be the same as the key. If `type` is `f` then it represents a double precision float. If `type` is `c` it represents a double precision complex, which is represented by [COMPLEX](#qpy-complex). Finally, if type is `i` it represents an integer which is an `int64_t`. + + + +#### COMPLEX + +When representing a double precision complex value in QPY the following struct is used: + +```python +struct { + double real; + double imag; +} +``` + +this matches the internal C representation of Python’s complex type. [\[3\]](#f3) + +\[[1](#id2)] + +[https://tools.ietf.org/html/rfc1700](https://tools.ietf.org/html/rfc1700) + +\[2] ([1](#id4),[2](#id6)) + +[https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html](https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html) + +\[[3](#id8)] + +[https://docs.python.org/3/c-api/complex.html#c.Py\_complex](https://docs.python.org/3/c-api/complex.html#c.Py_complex) + diff --git a/docs/api/qiskit/0.46/quantum_info.md b/docs/api/qiskit/0.46/quantum_info.md new file mode 100644 index 00000000000..c7f298768fa --- /dev/null +++ b/docs/api/qiskit/0.46/quantum_info.md @@ -0,0 +1,944 @@ +--- +title: quantum_info +description: API reference for qiskit.quantum_info +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.quantum_info +--- + + + + + + + +# Quantum Information + + + +`qiskit.quantum_info` + + + +## Operators + +| | | +| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| [`Operator`](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")(data\[, input\_dims, output\_dims]) | Matrix operator class | +| [`Pauli`](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli")(\[data]) | N-qubit Pauli operator. | +| [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")(data\[, validate, copy]) | An N-qubit unitary operator from the Clifford group. | +| [`ScalarOp`](qiskit.quantum_info.ScalarOp "qiskit.quantum_info.ScalarOp")(\[dims, coeff]) | Scalar identity operator class. | +| [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")(data\[, coeffs, ...]) | Sparse N-qubit operator in a Pauli basis representation. | +| [`CNOTDihedral`](qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")(\[data, num\_qubits, validate]) | An N-qubit operator from the CNOT-Dihedral group. | +| [`PauliList`](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList")(data) | List of N-qubit Pauli operators. | +| [`pauli_basis`](qiskit.quantum_info.pauli_basis "qiskit.quantum_info.pauli_basis")(num\_qubits\[, weight]) | Return the ordered PauliList for the n-qubit Pauli basis. | + + + +## States + +| | | +| ----------------------------------------------------------------------------------------------------------------- | ---------------------- | +| [`Statevector`](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")(data\[, dims]) | Statevector class | +| [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")(data\[, dims]) | DensityMatrix class | +| [`StabilizerState`](qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState")(data\[, validate]) | StabilizerState class. | + +## Channels + +| | | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| [`Choi`](qiskit.quantum_info.Choi "qiskit.quantum_info.Choi")(data\[, input\_dims, output\_dims]) | Choi-matrix representation of a Quantum Channel. | +| [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp")(data\[, input\_dims, output\_dims]) | Superoperator representation of a quantum channel. | +| [`Kraus`](qiskit.quantum_info.Kraus "qiskit.quantum_info.Kraus")(data\[, input\_dims, output\_dims]) | Kraus representation of a quantum channel. | +| [`Stinespring`](qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring")(data\[, input\_dims, output\_dims]) | Stinespring representation of a quantum channel. | +| [`Chi`](qiskit.quantum_info.Chi "qiskit.quantum_info.Chi")(data\[, input\_dims, output\_dims]) | Pauli basis Chi-matrix representation of a quantum channel. | +| [`PTM`](qiskit.quantum_info.PTM "qiskit.quantum_info.PTM")(data\[, input\_dims, output\_dims]) | Pauli Transfer Matrix (PTM) representation of a Quantum Channel. | + +## Measures + +### average\_gate\_fidelity + + + +`qiskit.quantum_info.average_gate_fidelity(channel, target=None, require_cp=True, require_tp=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/measures.py "view source code") + +Return the average gate fidelity of a noisy quantum channel. + +The average gate fidelity $F_{\text{ave}}$ is given by + +$$ +\begin{aligned} +F_{\text{ave}}(\mathcal{E}, U) + &= \int d\psi \langle\psi|U^\dagger + \mathcal{E}(|\psi\rangle\!\langle\psi|)U|\psi\rangle \\ + &= \frac{d F_{\text{pro}}(\mathcal{E}, U) + 1}{d + 1} +\end{aligned} + + +$$ + +where $F_{\text{pro}}(\mathcal{E}, U)$ is the [`process_fidelity()`](#qiskit.quantum_info.process_fidelity "qiskit.quantum_info.process_fidelity") of the input quantum *channel* $\mathcal{E}$ with a *target* unitary $U$, and $d$ is the dimension of the *channel*. + +**Parameters** + +* **channel** (*QuantumChannel or* [*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – noisy quantum channel. +* **target** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") *or None*) – target unitary operator. If None target is the identity operator \[Default: None]. +* **require\_cp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input and target channels are completely-positive and if non-CP log warning containing negative eigenvalues of Choi-matrix \[Default: True]. +* **require\_tp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input and target channels are trace-preserving and if non-TP log warning containing negative eigenvalues of partial Choi-matrix $Tr_{\text{out}}[\mathcal{E}] - I$ \[Default: True]. + +**Returns** + +The average gate fidelity $F_{\text{ave}}$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the channel and target do not have the same dimensions, or have different input and output dimensions. + +### process\_fidelity + + + +`qiskit.quantum_info.process_fidelity(channel, target=None, require_cp=True, require_tp=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/measures.py "view source code") + +Return the process fidelity of a noisy quantum channel. + +The process fidelity $F_{\text{pro}}(\mathcal{E}, \mathcal{F})$ between two quantum channels $\mathcal{E}, \mathcal{F}$ is given by + +$$ +F_{\text{pro}}(\mathcal{E}, \mathcal{F}) + = F(\rho_{\mathcal{E}}, \rho_{\mathcal{F}}) + + +$$ + +where $F$ is the [`state_fidelity()`](#qiskit.quantum_info.state_fidelity "qiskit.quantum_info.state_fidelity"), $\rho_{\mathcal{E}} = \Lambda_{\mathcal{E}} / d$ is the normalized [`Choi`](qiskit.quantum_info.Choi "qiskit.quantum_info.Choi") matrix for the channel $\mathcal{E}$, and $d$ is the input dimension of $\mathcal{E}$. + +When the target channel is unitary this is equivalent to + +$$ +F_{\text{pro}}(\mathcal{E}, U) + = \frac{Tr[S_U^\dagger S_{\mathcal{E}}]}{d^2} + + +$$ + +where $S_{\mathcal{E}}, S_{U}$ are the [`SuperOp`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") matrices for the *input* quantum channel $\mathcal{E}$ and *target* unitary $U$ respectively, and $d$ is the input dimension of the channel. + +**Parameters** + +* **channel** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") *or QuantumChannel*) – input quantum channel. +* **target** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") *or QuantumChannel or None*) – target quantum channel. If None target is the identity operator \[Default: None]. +* **require\_cp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input and target channels are completely-positive and if non-CP log warning containing negative eigenvalues of Choi-matrix \[Default: True]. +* **require\_tp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input and target channels are trace-preserving and if non-TP log warning containing negative eigenvalues of partial Choi-matrix $Tr_{\text{out}}[\mathcal{E}] - I$ \[Default: True]. + +**Returns** + +The process fidelity $F_{\text{pro}}$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the channel and target do not have the same dimensions. + +### gate\_error + + + +`qiskit.quantum_info.gate_error(channel, target=None, require_cp=True, require_tp=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/measures.py "view source code") + +Return the gate error of a noisy quantum channel. + +The gate error $E$ is given by the average gate infidelity + +$$ +E(\mathcal{E}, U) = 1 - F_{\text{ave}}(\mathcal{E}, U) + + +$$ + +where $F_{\text{ave}}(\mathcal{E}, U)$ is the [`average_gate_fidelity()`](#qiskit.quantum_info.average_gate_fidelity "qiskit.quantum_info.average_gate_fidelity") of the input quantum *channel* $\mathcal{E}$ with a *target* unitary $U$. + +**Parameters** + +* **channel** (*QuantumChannel*) – noisy quantum channel. +* **target** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") *or None*) – target unitary operator. If None target is the identity operator \[Default: None]. +* **require\_cp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input and target channels are completely-positive and if non-CP log warning containing negative eigenvalues of Choi-matrix \[Default: True]. +* **require\_tp** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input and target channels are trace-preserving and if non-TP log warning containing negative eigenvalues of partial Choi-matrix $Tr_{\text{out}}[\mathcal{E}] - I$ \[Default: True]. + +**Returns** + +The average gate error $E$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the channel and target do not have the same dimensions, or have different input and output dimensions. + +### diamond\_norm + + + +`qiskit.quantum_info.diamond_norm(choi, solver='SCS', **kwargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/measures.py "view source code") + +Return the diamond norm of the input quantum channel object. + +This function computes the completely-bounded trace-norm (often referred to as the diamond-norm) of the input quantum channel object using the semidefinite-program from reference \[1]. + +**Parameters** + +* **choi** ([*Choi*](qiskit.quantum_info.Choi "qiskit.quantum_info.Choi") *or QuantumChannel*) – a quantum channel object or Choi-matrix array. +* **solver** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The solver to use. +* **kwargs** – optional arguments to pass to CVXPY solver. + +**Returns** + +The completely-bounded trace norm $\|\mathcal{E}\|_{\diamond}$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if CVXPY package cannot be found. + +**Additional Information:** + +The input to this function is typically *not* a CPTP quantum channel, but rather the *difference* between two quantum channels $\|\Delta\mathcal{E}\|_\diamond$ where $\Delta\mathcal{E} = \mathcal{E}_1 - \mathcal{E}_2$. + +**Reference:** + +J. Watrous. “Simpler semidefinite programs for completely bounded norms”, arXiv:1207.5726 \[quant-ph] (2012). + + + This function requires the optional CVXPY package to be installed. Any additional kwargs will be passed to the `cvxpy.solve` function. See the CVXPY documentation for information on available SDP solvers. + + +### state\_fidelity + + + +`qiskit.quantum_info.state_fidelity(state1, state2, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/measures.py "view source code") + +Return the state fidelity between two quantum states. + +The state fidelity $F$ for density matrix input states $\rho_1, \rho_2$ is given by + +$$ +F(\rho_1, \rho_2) = Tr[\sqrt{\sqrt{\rho_1}\rho_2\sqrt{\rho_1}}]^2. + + +$$ + +If one of the states is a pure state this simplifies to $F(\rho_1, \rho_2) = \langle\psi_1|\rho_2|\psi_1\rangle$, where $\rho_1 = |\psi_1\rangle\!\langle\psi_1|$. + +**Parameters** + +* **state1** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – the first quantum state. +* **state2** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – the second quantum state. +* **validate** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if the inputs are valid quantum states \[Default: True] + +**Returns** + +The state fidelity $F(\rho_1, \rho_2)$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if `validate=True` and the inputs are invalid quantum states. + +### purity + + + +`qiskit.quantum_info.purity(state, validate=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/measures.py "view source code") + +Calculate the purity of a quantum state. + +The purity of a density matrix $\rho$ is + +$$ +\text{Purity}(\rho) = Tr[\rho^2] +$$ + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a quantum state. +* **validate** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – check if input state is valid \[Default: True] + +**Returns** + +the purity $Tr[\rho^2]$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input isn’t a valid quantum state. + +### concurrence + + + +`qiskit.quantum_info.concurrence(state)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/measures.py "view source code") + +Calculate the concurrence of a quantum state. + +The concurrence of a bipartite [`Statevector`](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") $|\psi\rangle$ is given by + +$$ +C(|\psi\rangle) = \sqrt{2(1 - Tr[\rho_0^2])} +$$ + +where $\rho_0 = Tr_1[|\psi\rangle\!\langle\psi|]$ is the reduced state from by taking the [`partial_trace()`](#qiskit.quantum_info.partial_trace "qiskit.quantum_info.partial_trace") of the input state. + +For density matrices the concurrence is only defined for 2-qubit states, it is given by: + +$$ +C(\rho) = \max(0, \lambda_1 - \lambda_2 - \lambda_3 - \lambda_4) +$$ + +where $\lambda _1 \ge \lambda _2 \ge \lambda _3 \ge \lambda _4$ are the ordered eigenvalues of the matrix $R=\sqrt{\sqrt{\rho }(Y\otimes Y)\overline{\rho}(Y\otimes Y)\sqrt{\rho}}$. + +**Parameters** + +**state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a 2-qubit quantum state. + +**Returns** + +The concurrence. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input state is not a valid QuantumState. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input is not a bipartite QuantumState. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if density matrix input is not a 2-qubit state. + +### entropy + + + +`qiskit.quantum_info.entropy(state, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/measures.py "view source code") + +Calculate the von-Neumann entropy of a quantum state. + +The entropy $S$ is given by + +$$ +S(\rho) = - Tr[\rho \log(\rho)] +$$ + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a quantum state. +* **base** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the base of the logarithm \[Default: 2]. + +**Returns** + +The von-Neumann entropy S(rho). + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input state is not a valid QuantumState. + +### entanglement\_of\_formation + + + +`qiskit.quantum_info.entanglement_of_formation(state)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/measures.py "view source code") + +Calculate the entanglement of formation of quantum state. + +The input quantum state must be either a bipartite state vector, or a 2-qubit density matrix. + +**Parameters** + +**state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a 2-qubit quantum state. + +**Returns** + +The entanglement of formation. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input state is not a valid QuantumState. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input is not a bipartite QuantumState. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if density matrix input is not a 2-qubit state. + +### mutual\_information + + + +`qiskit.quantum_info.mutual_information(state, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/measures.py "view source code") + +Calculate the mutual information of a bipartite state. + +The mutual information $I$ is given by: + +$$ +I(\rho_{AB}) = S(\rho_A) + S(\rho_B) - S(\rho_{AB}) +$$ + +where $\rho_A=Tr_B[\rho_{AB}], \rho_B=Tr_A[\rho_{AB}]$, are the reduced density matrices of the bipartite state $\rho_{AB}$. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a bipartite state. +* **base** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the base of the logarithm \[Default: 2]. + +**Returns** + +The mutual information $I(\rho_{AB})$. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input state is not a valid QuantumState. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input is not a bipartite QuantumState. + +## Utility Functions + +| | | +| ------------------------------------------------------------------------------------- | ---------------------------------- | +| [`Quaternion`](qiskit.quantum_info.Quaternion "qiskit.quantum_info.Quaternion")(data) | A class representing a Quaternion. | + +### partial\_trace + + + +`qiskit.quantum_info.partial_trace(state, qargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/utils.py "view source code") + +Return reduced density matrix by tracing out part of quantum state. + +If all subsystems are traced over this returns the [`trace()`](qiskit.quantum_info.DensityMatrix#trace "qiskit.quantum_info.DensityMatrix.trace") of the input state. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – the input state. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – The subsystems to trace over. + +**Returns** + +The reduced density matrix. + +**Return type** + +[DensityMatrix](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if input state is invalid. + +### schmidt\_decomposition + + + +`qiskit.quantum_info.schmidt_decomposition(state, qargs)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/utils.py "view source code") + +Return the Schmidt Decomposition of a pure quantum state. + +For an arbitrary bipartite state: + +$$ +|\psi\rangle_{AB} = \sum_{i,j} c_{ij} + |x_i\rangle_A \otimes |y_j\rangle_B, + + +$$ + +its Schmidt Decomposition is given by the single-index sum over k: + +$$ +|\psi\rangle_{AB} = \sum_{k} \lambda_{k} + |u_k\rangle_A \otimes |v_k\rangle_B + + +$$ + +where $|u_k\rangle_A$ and $|v_k\rangle_B$ are an orthonormal set of vectors in their respective spaces $A$ and $B$, and the Schmidt coefficients $\lambda_k$ are positive real values. + +**Parameters** + +* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *or*[*DensityMatrix*](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – the input state. +* **qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – the list of Input state positions corresponding to subsystem $B$. + +**Returns** + +list of tuples `(s, u, v)`, where `s` (float) are the Schmidt coefficients $\lambda_k$, and `u` (Statevector), `v` (Statevector) are the Schmidt vectors $|u_k\rangle_A$, $|u_k\rangle_B$, respectively. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if Input qargs is not a list of positions of the Input state. +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if Input qargs is not a proper subset of Input state. + + + In Qiskit, qubits are ordered using little-endian notation, with the least significant qubits having smaller indices. For example, a four-qubit system is represented as $|q_3q_2q_1q_0\rangle$. Using this convention, setting `qargs=[0]` will partition the state as $|q_3q_2q_1\rangle_A\otimes|q_0\rangle_B$. Furthermore, qubits will be organized in this notation regardless of the order they are passed. For instance, passing either `qargs=[1,2]` or `qargs=[2,1]` will result in partitioning the state as $|q_3q_0\rangle_A\otimes|q_2q_1\rangle_B$. + + +### shannon\_entropy + + + +`qiskit.quantum_info.shannon_entropy(pvec, base=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/utils.py "view source code") + +Compute the Shannon entropy of a probability vector. + +The shannon entropy of a probability vector $\vec{p} = [p_0, ..., p_{n-1}]$ is defined as + +$$ +H(\vec{p}) = \sum_{i=0}^{n-1} p_i \log_b(p_i) +$$ + +where $b$ is the log base and (default 2), and $0 \log_b(0) \equiv 0$. + +**Parameters** + +* **pvec** (*array\_like*) – a probability vector. +* **base** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the base of the logarithm \[Default: 2]. + +**Returns** + +The Shannon entropy H(pvec). + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +### commutator + + + +`qiskit.quantum_info.commutator(a, b)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/utils/commutator.py "view source code") + +Compute commutator of a and b. + +$$ +ab - ba. +$$ + +**Parameters** + +* **a** (*OperatorTypeT*) – Operator a. +* **b** (*OperatorTypeT*) – Operator b. + +**Returns** + +The commutator + +**Return type** + +*OperatorTypeT* + +### anti\_commutator + + + +`qiskit.quantum_info.anti_commutator(a, b)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/utils/anti_commutator.py "view source code") + +Compute anti-commutator of a and b. + +$$ +ab + ba. +$$ + +**Parameters** + +* **a** (*OperatorTypeT*) – Operator a. +* **b** (*OperatorTypeT*) – Operator b. + +**Returns** + +The anti-commutator + +**Return type** + +*OperatorTypeT* + +### double\_commutator + + + +`qiskit.quantum_info.double_commutator(a, b, c, *, commutator=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/utils/double_commutator.py "view source code") + +Compute symmetric double commutator of a, b and c. + +See also Equation (13.6.18) in \[1]. + +If commutator is True, it returns + +$$ +[[A, B], C]/2 + [A, [B, C]]/2 += (2ABC + 2CBA - BAC - CAB - ACB - BCA)/2. +$$ + +If commutator is False, it returns + +$$ +\lbrace[A, B], C\rbrace/2 + \lbrace A, [B, C]\rbrace/2 += (2ABC - 2CBA - BAC + CAB - ACB + BCA)/2. + + +$$ + +**Parameters** + +* **a** (*OperatorTypeT*) – Operator a. +* **b** (*OperatorTypeT*) – Operator b. +* **c** (*OperatorTypeT*) – Operator c. +* **commutator** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` compute the double commutator, if `False` the double anti-commutator. + +**Returns** + +The double commutator + +**Return type** + +*OperatorTypeT* + +**References** + +**\[1]: R. McWeeny.** + +Methods of Molecular Quantum Mechanics. 2nd Edition, Academic Press, 1992. ISBN 0-12-486552-6. + +## Random + +### random\_statevector + + + +`qiskit.quantum_info.random_statevector(dims, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/random.py "view source code") + +Generator a random Statevector. + +The statevector is sampled from the uniform distribution. This is the measure induced by the Haar measure on unitary matrices. + +**Parameters** + +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the dimensions of the state. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +the random statevector. + +**Return type** + +[Statevector](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") + +**Reference:** + +K. Zyczkowski and H. Sommers (2001), “Induced measures in the space of mixed quantum states”, [J. Phys. A: Math. Gen. 34 7111](https://arxiv.org/abs/quant-ph/0012101). + +### random\_density\_matrix + + + +`qiskit.quantum_info.random_density_matrix(dims, rank=None, method='Hilbert-Schmidt', seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/states/random.py "view source code") + +Generator a random DensityMatrix. + +**Parameters** + +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the dimensions of the DensityMatrix. +* **rank** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or None*) – Optional, the rank of the density matrix. The default value is full-rank. +* **method** (*string*) – Optional. The method to use. ‘Hilbert-Schmidt’: (Default) sample from the Hilbert-Schmidt metric. ‘Bures’: sample from the Bures metric. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +the random density matrix. + +**Return type** + +[DensityMatrix](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the method is not valid. + +### random\_unitary + + + +`qiskit.quantum_info.random_unitary(dims, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/random.py "view source code") + +Return a random unitary Operator. + +The operator is sampled from the unitary Haar measure. + +**Parameters** + +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input dimensions of the Operator. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +a unitary operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +### random\_hermitian + + + +`qiskit.quantum_info.random_hermitian(dims, traceless=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/random.py "view source code") + +Return a random hermitian Operator. + +The operator is sampled from Gaussian Unitary Ensemble. + +**Parameters** + +* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input dimension of the Operator. +* **traceless** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional. If True subtract diagonal entries to return a traceless hermitian operator (Default: False). +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +a Hermitian operator. + +**Return type** + +[Operator](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator") + +### random\_pauli + + + +`qiskit.quantum_info.random_pauli(num_qubits, group_phase=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/random.py "view source code") + +Return a random Pauli. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits. +* **group\_phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Optional. If True generate random phase. Otherwise the phase will be set so that the Pauli coefficient is +1 (default: False). +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +a random Pauli + +**Return type** + +[Pauli](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") + +### random\_clifford + + + +`qiskit.quantum_info.random_clifford(num_qubits, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/random.py "view source code") + +Return a random Clifford operator. + +The Clifford is sampled using the method of Reference \[1]. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits for the Clifford +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +a random Clifford operator. + +**Return type** + +[Clifford](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") + +**Reference:** + +1. S. Bravyi and D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*. [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) + +### random\_quantum\_channel + + + +`qiskit.quantum_info.random_quantum_channel(input_dims=None, output_dims=None, rank=None, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/random.py "view source code") + +Return a random CPTP quantum channel. + +This constructs the Stinespring operator for the quantum channel by sampling a random isometry from the unitary Haar measure. + +**Parameters** + +* **input\_dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input dimension of the channel. +* **output\_dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")) – the input dimension of the channel. +* **rank** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The rank of the quantum channel Choi-matrix. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +a quantum channel operator. + +**Return type** + +[Stinespring](qiskit.quantum_info.Stinespring "qiskit.quantum_info.Stinespring") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if rank or dimensions are invalid. + +### random\_cnotdihedral + + + +`qiskit.quantum_info.random_cnotdihedral(num_qubits, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/dihedral/random.py "view source code") + +Return a random CNOTDihedral element. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits for the CNOTDihedral object. +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or RandomState*) – Optional. Set a fixed seed or generator for RNG. + +**Returns** + +a random CNOTDihedral element. + +**Return type** + +[CNOTDihedral](qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral") + +### random\_pauli\_list + + + +`qiskit.quantum_info.random_pauli_list(num_qubits, size=1, seed=None, phase=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/operators/symplectic/random.py "view source code") + +Return a random PauliList. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the number of qubits. +* **size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Optional. The length of the Pauli list (Default: 1). +* **seed** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *or np.random.Generator*) – Optional. Set a fixed seed or generator for RNG. +* **phase** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True the Pauli phases are randomized, otherwise the phases are fixed to 0. \[Default: True] + +**Returns** + +a random PauliList. + +**Return type** + +[PauliList](qiskit.quantum_info.PauliList "qiskit.quantum_info.PauliList") + +## Analysis + +### hellinger\_distance + + + +`qiskit.quantum_info.hellinger_distance(dist_p, dist_q)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/analysis/distance.py "view source code") + +Computes the Hellinger distance between two counts distributions. + +**Parameters** + +* **dist\_p** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – First dict of counts. +* **dist\_q** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Second dict of counts. + +**Returns** + +Distance + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**References** + +[Hellinger Distance @ wikipedia](https://en.wikipedia.org/wiki/Hellinger_distance) + +### hellinger\_fidelity + + + +`qiskit.quantum_info.hellinger_fidelity(dist_p, dist_q)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/quantum_info/analysis/distance.py "view source code") + +Computes the Hellinger fidelity between two counts distributions. + +The fidelity is defined as $\left(1-H^{2}\right)^{2}$ where H is the Hellinger distance. This value is bounded in the range \[0, 1]. + +This is equivalent to the standard classical fidelity $F(Q,P)=\left(\sum_{i}\sqrt{p_{i}q_{i}}\right)^{2}$ that in turn is equal to the quantum state fidelity for diagonal density matrices. + +**Parameters** + +* **dist\_p** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – First dict of counts. +* **dist\_q** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Second dict of counts. + +**Returns** + +Fidelity + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Example** + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info.analysis import hellinger_fidelity +from qiskit.providers.basic_provider import BasicSimulator + +qc = QuantumCircuit(5, 5) +qc.h(2) +qc.cx(2, 1) +qc.cx(2, 3) +qc.cx(3, 4) +qc.cx(1, 0) +qc.measure(range(5), range(5)) + +sim = BasicSimulator() +res1 = sim.run(qc).result() +res2 = sim.run(qc).result() + +hellinger_fidelity(res1.get_counts(), res2.get_counts()) +``` + +**References** + +[Quantum Fidelity @ wikipedia](https://en.wikipedia.org/wiki/Fidelity_of_quantum_states) [Hellinger Distance @ wikipedia](https://en.wikipedia.org/wiki/Hellinger_distance) + +| | | +| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`Z2Symmetries`](qiskit.quantum_info.Z2Symmetries "qiskit.quantum_info.Z2Symmetries")(symmetries, sq\_paulis, sq\_list) | The \$Z\_2\$ symmetry converter identifies symmetries from the problem hamiltonian and uses them to provide a tapered - more efficient - representation of operators as Paulis for this problem. | + diff --git a/docs/api/qiskit/0.46/result.md b/docs/api/qiskit/0.46/result.md new file mode 100644 index 00000000000..3d0e674bce6 --- /dev/null +++ b/docs/api/qiskit/0.46/result.md @@ -0,0 +1,160 @@ +--- +title: result +description: API reference for qiskit.result +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.result +--- + + + + + + + +# Experiment Results + + + +`qiskit.result` + +| | | +| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| [`Result`](qiskit.result.Result "qiskit.result.Result")(backend\_name, backend\_version, ...\[, ...]) | Model for Results. | +| [`ResultError`](qiskit.result.ResultError "qiskit.result.ResultError")(error) | Exceptions raised due to errors in result output. | +| [`Counts`](qiskit.result.Counts "qiskit.result.Counts")(data\[, time\_taken, creg\_sizes, ...]) | A class to store a counts result from a circuit execution. | + +### marginal\_counts + + + +`qiskit.result.marginal_counts(result, indices=None, inplace=False, format_marginal=False, marginalize_memory=True)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/utils.py "view source code") + +Marginalize counts from an experiment over some indices of interest. + +**Parameters** + +* **result** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *|*[*Result*](qiskit.result.Result "qiskit.result.result.Result")) – result to be marginalized (a Result object or a dict(str, int) of counts). +* **indices** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – The bit positions of interest to marginalize over. If `None` (default), do not marginalize at all. +* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Default: False. Operates on the original Result argument if True, leading to loss of original Job Result. It has no effect if `result` is a dict. +* **format\_marginal** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Default: False. If True, takes the output of marginalize and formats it with placeholders between cregs and for non-indices. +* **marginalize\_memory** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") *| None*) – If True, then also marginalize the memory field (if present). If False, remove the memory field from the result. If None, leave the memory field as is. + +**Returns** + +**A Result object or a dictionary with** + +the observed counts, marginalized to only account for frequency of observations of bits of interest. + +**Return type** + +[Result](qiskit.result.Result "qiskit.result.Result") or [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")([str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – in case of invalid indices to marginalize over. + +### marginal\_distribution + + + +`qiskit.result.marginal_distribution(counts, indices=None, format_marginal=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/utils.py "view source code") + +Marginalize counts from an experiment over some indices of interest. + +Unlike [`marginal_counts()`](#qiskit.result.marginal_counts "qiskit.result.marginal_counts") this function respects the order of the input `indices`. If the input `indices` list is specified then the order the bit indices are specified will be the output order of the bitstrings in the marginalized output. + +**Parameters** + +* **counts** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – result to be marginalized +* **indices** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – The bit positions of interest to marginalize over. If `None` (default), do not marginalize at all. +* **format\_marginal** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Default: False. If True, takes the output of marginalize and formats it with placeholders between cregs and for non-indices. + +**Returns** + +A marginalized dictionary + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")([str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If any value in `indices` is invalid or the `counts` dict +* **is invalid.** – + +### marginal\_memory + + + +`qiskit.result.marginal_memory(memory, indices=None, int_return=False, hex_return=False, avg_data=False, parallel_threshold=1000)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/utils.py "view source code") + +Marginalize shot memory + +This function is multithreaded and will launch a thread pool with threads equal to the number of CPUs by default. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. + +**Parameters** + +* **memory** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*] |* [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – The input memory list, this is either a list of hexadecimal strings to be marginalized representing measure level 2 memory or a numpy array representing level 0 measurement memory (single or avg) or level 1 measurement memory (single or avg). +* **indices** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – The bit positions of interest to marginalize over. If `None` (default), do not marginalize at all. +* **int\_return** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` the output will be a list of integers. By default the return type is a bit string. This and `hex_return` are mutually exclusive and can not be specified at the same time. This option only has an effect with memory level 2. +* **hex\_return** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to `True` the output will be a list of hexadecimal strings. By default the return type is a bit string. This and `int_return` are mutually exclusive and can not be specified at the same time. This option only has an effect with memory level 2. +* **avg\_data** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If a 2 dimensional numpy array is passed in for `memory` this can be set to `True` to indicate it’s a avg level 0 data instead of level 1 single data. +* **parallel\_threshold** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The number of elements in `memory` to start running in multiple threads. If `len(memory)` is >= this value, the function will run in multiple threads. By default this is set to 1000. + +**Returns** + +The list of marginalized memory + +**Return type** + +marginal\_memory + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if both `int_return` and `hex_return` are set to `True` + +## Distributions + +| | | +| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| [`ProbDistribution`](qiskit.result.ProbDistribution "qiskit.result.ProbDistribution")(data\[, shots]) | A generic dict-like class for probability distributions. | +| [`QuasiDistribution`](qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution")(data\[, shots, ...]) | A dict-like class for representing quasi-probabilities. | + +## Expectation values + +### sampled\_expectation\_value + + + +`qiskit.result.sampled_expectation_value(dist, oper)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/result/sampled_expval.py "view source code") + +Computes expectation value from a sampled distribution + +Note that passing a raw dict requires bit-string keys. + +**Parameters** + +* **dist** ([*Counts*](qiskit.result.Counts "qiskit.result.Counts") *or*[*QuasiDistribution*](qiskit.result.QuasiDistribution "qiskit.result.QuasiDistribution") *or*[*ProbDistribution*](qiskit.result.ProbDistribution "qiskit.result.ProbDistribution") *or*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Input sampled distribution +* **oper** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*Pauli*](qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") *or*[*PauliOp*](qiskit.opflow.primitive_ops.PauliOp "qiskit.opflow.primitive_ops.PauliOp") *or*[*PauliSumOp*](qiskit.opflow.primitive_ops.PauliSumOp "qiskit.opflow.primitive_ops.PauliSumOp") *or*[*SparsePauliOp*](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp")) – The operator for the observable + +**Returns** + +The expectation value + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input distribution or operator is an invalid type + +## Mitigation + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| [`BaseReadoutMitigator`](qiskit.result.BaseReadoutMitigator "qiskit.result.BaseReadoutMitigator")() | Base readout error mitigator class. | +| [`CorrelatedReadoutMitigator`](qiskit.result.CorrelatedReadoutMitigator "qiskit.result.CorrelatedReadoutMitigator")(assignment\_matrix) | N-qubit readout error mitigator. | +| [`LocalReadoutMitigator`](qiskit.result.LocalReadoutMitigator "qiskit.result.LocalReadoutMitigator")(\[assignment\_matrices, ...]) | 1-qubit tensor product readout error mitigator. | + diff --git a/docs/api/qiskit/0.46/scheduler.md b/docs/api/qiskit/0.46/scheduler.md new file mode 100644 index 00000000000..eb0d6427858 --- /dev/null +++ b/docs/api/qiskit/0.46/scheduler.md @@ -0,0 +1,122 @@ +--- +title: scheduler +description: API reference for qiskit.scheduler +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.scheduler +--- + + + + + + + +# Circuit Scheduler + + + +`qiskit.scheduler` + +A circuit scheduler compiles a circuit program to a pulse program. + + + +`qiskit.scheduler.ScheduleConfig(inst_map, meas_map, dt)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/scheduler/config.py "view source code") + +Configuration for pulse scheduling. + +Container for information needed to schedule a QuantumCircuit into a pulse Schedule. + +**Parameters** + +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.instruction_schedule_map.InstructionScheduleMap")) – The schedule definition of all gates supported on a backend. +* **meas\_map** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]]*) – A list of groups of qubits which have to be measured together. +* **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Sample duration. + +### schedule\_circuit + + + +`qiskit.scheduler.schedule_circuit.schedule_circuit(circuit, schedule_config, method=None, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/scheduler/schedule_circuit.py "view source code") + +Basic scheduling pass from a circuit to a pulse Schedule, using the backend. If no method is specified, then a basic, as late as possible scheduling pass is performed, i.e. pulses are scheduled to occur as late as possible. + +Supported methods: + +> * `'as_soon_as_possible'`: Schedule pulses greedily, as early as possible on a qubit resource. (alias: `'asap'`) +> * `'as_late_as_possible'`: Schedule pulses late– keep qubits in the ground state when possible. (alias: `'alap'`) + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The quantum circuit to translate. +* **schedule\_config** ([*ScheduleConfig*](#qiskit.scheduler.ScheduleConfig "qiskit.scheduler.config.ScheduleConfig")) – Backend specific parameters used for building the Schedule. +* **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The scheduling pass method to use. +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.backend.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") *| None*) – A backend used to build the Schedule, the backend could be BackendV1 or BackendV2. + +**Returns** + +Schedule corresponding to the input circuit. + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If method isn’t recognized. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + + + +Pulse scheduling methods. + +### as\_soon\_as\_possible + + + +`qiskit.scheduler.methods.as_soon_as_possible(circuit, schedule_config, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/scheduler/methods/basic.py "view source code") + +Return the pulse Schedule which implements the input circuit using an “as soon as possible” (asap) scheduling policy. + +Circuit instructions are first each mapped to equivalent pulse Schedules according to the command definition given by the schedule\_config. Then, this circuit instruction-equivalent Schedule is appended at the earliest time at which all qubits involved in the instruction are available. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The quantum circuit to translate. +* **schedule\_config** ([*ScheduleConfig*](#qiskit.scheduler.ScheduleConfig "qiskit.scheduler.config.ScheduleConfig")) – Backend specific parameters used for building the Schedule. +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.backend.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") *| None*) – A backend used to build the Schedule, the backend could be BackendV1 or BackendV2. + +**Returns** + +A schedule corresponding to the input `circuit` with pulses occurring as early as possible. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + +### as\_late\_as\_possible + + + +`qiskit.scheduler.methods.as_late_as_possible(circuit, schedule_config, backend=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/scheduler/methods/basic.py "view source code") + +Return the pulse Schedule which implements the input circuit using an “as late as possible” (alap) scheduling policy. + +Circuit instructions are first each mapped to equivalent pulse Schedules according to the command definition given by the schedule\_config. Then, this circuit instruction-equivalent Schedule is appended at the latest time that it can be without allowing unnecessary time between instructions or allowing instructions with common qubits to overlap. + +This method should improves the outcome fidelity over ASAP scheduling, because we may maximize the time that the qubit remains in the ground state. + +**Parameters** + +* **circuit** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")) – The quantum circuit to translate. +* **schedule\_config** ([*ScheduleConfig*](#qiskit.scheduler.ScheduleConfig "qiskit.scheduler.config.ScheduleConfig")) – Backend specific parameters used for building the Schedule. +* **backend** ([*BackendV1*](qiskit.providers.BackendV1 "qiskit.providers.backend.BackendV1") *|*[*BackendV2*](qiskit.providers.BackendV2 "qiskit.providers.backend.BackendV2") *| None*) – A backend used to build the Schedule, the backend could be BackendV1 or BackendV2. + +**Returns** + +A schedule corresponding to the input `circuit` with pulses occurring as late as possible. + +**Return type** + +[*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule") + diff --git a/docs/api/qiskit/0.46/synthesis.md b/docs/api/qiskit/0.46/synthesis.md new file mode 100644 index 00000000000..bb841c6ed7c --- /dev/null +++ b/docs/api/qiskit/0.46/synthesis.md @@ -0,0 +1,729 @@ +--- +title: synthesis +description: API reference for qiskit.synthesis +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.synthesis +--- + + + + + + + +# Circuit Synthesis + + + +`qiskit.synthesis` + + + +## Evolution Synthesis + +| | | +| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [`EvolutionSynthesis`](qiskit.synthesis.EvolutionSynthesis "qiskit.synthesis.EvolutionSynthesis")() | Interface for evolution synthesis algorithms. | +| [`ProductFormula`](qiskit.synthesis.ProductFormula "qiskit.synthesis.ProductFormula")(order\[, reps, ...]) | Product formula base class for the decomposition of non-commuting operator exponentials. | +| [`LieTrotter`](qiskit.synthesis.LieTrotter "qiskit.synthesis.LieTrotter")(\[reps, insert\_barriers, ...]) | The Lie-Trotter product formula. | +| [`SuzukiTrotter`](qiskit.synthesis.SuzukiTrotter "qiskit.synthesis.SuzukiTrotter")(\[order, reps, ...]) | The (higher order) Suzuki-Trotter product formula. | +| [`MatrixExponential`](qiskit.synthesis.MatrixExponential "qiskit.synthesis.MatrixExponential")() | Exact operator evolution via matrix exponentiation and unitary synthesis. | +| [`QDrift`](qiskit.synthesis.QDrift "qiskit.synthesis.QDrift")(\[reps, insert\_barriers, ...]) | The QDrift Trotterization method, which selects each each term in the Trotterization randomly, with a probability proportional to its weight. | + +## Linear Function Synthesis + +### synth\_cnot\_count\_full\_pmh + + + +`qiskit.synthesis.synth_cnot_count_full_pmh(state, section_size=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/linear/cnot_synth.py "view source code") + +Synthesize linear reversible circuits for all-to-all architecture using Patel, Markov and Hayes method. + +This function is an implementation of the Patel, Markov and Hayes algorithm from \[1] for optimal synthesis of linear reversible circuits for all-to-all architecture, as specified by an n x n matrix. + +**Parameters** + +* **state** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*] or ndarray*) – n x n boolean invertible matrix, describing the state of the input circuit +* **section\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the size of each section, used in the Patel–Markov–Hayes algorithm \[1]. section\_size must be a factor of num\_qubits. + +**Returns** + +a CX-only circuit implementing the linear transformation. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – when variable “state” isn’t of type numpy.ndarray + +**References** + +1. Patel, Ketan N., Igor L. Markov, and John P. Hayes, *Optimal synthesis of linear reversible circuits*, Quantum Information & Computation 8.3 (2008): 282-294. [arXiv:quant-ph/0302002 \[quant-ph\]](https://arxiv.org/abs/quant-ph/0302002) + +### synth\_cnot\_depth\_line\_kms + + + +`qiskit.synthesis.synth_cnot_depth_line_kms(mat)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/linear/linear_depth_lnn.py "view source code") + +Synthesize linear reversible circuit for linear nearest-neighbor architectures using Kutin, Moulton, Smithline method. + +Synthesis algorithm for linear reversible circuits from \[1], Chapter 7. Synthesizes any linear reversible circuit of n qubits over linear nearest-neighbor architecture using CX gates with depth at most 5\*n. + +**Parameters** + +**mat** (*np.ndarray]*) – A boolean invertible matrix. + +**Returns** + +the synthesized quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if mat is not invertible. + +**References** + +1. Kutin, S., Moulton, D. P., Smithline, L., *Computation at a distance*, Chicago J. Theor. Comput. Sci., vol. 2007, (2007), [arXiv:quant-ph/0701194](https://arxiv.org/abs/quant-ph/0701194) + +## Linear-Phase Synthesis + +### synth\_cz\_depth\_line\_mr + + + +`qiskit.synthesis.synth_cz_depth_line_mr(mat)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/linear_phase/cz_depth_lnn.py "view source code") + +Synthesis of a CZ circuit for linear nearest neighbour (LNN) connectivity, based on Maslov and Roetteler. + +Note that this method *reverts* the order of qubits in the circuit, and returns a circuit containing CX and phase (S, Sdg or Z) gates. + +**Parameters** + +**mat** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – an upper-diagonal matrix representing the CZ circuit. mat\[i]\[j]=1 for i\ + +`qiskit.synthesis.synth_cx_cz_depth_line_my(mat_x, mat_z)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/linear_phase/cx_cz_depth_lnn.py "view source code") + +Joint synthesis of a -CZ-CX- circuit for linear nearest neighbour (LNN) connectivity, with 2-qubit depth at most 5n, based on Maslov and Yang. This method computes the CZ circuit inside the CX circuit via phase gate insertions. + +**Parameters** + +* **mat\_z** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a boolean symmetric matrix representing a CZ circuit. Mz\[i]\[j]=1 represents a CZ(i,j) gate +* **mat\_x** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)")) – a boolean invertible matrix representing a CX circuit. + +**Returns** + +a circuit implementation of a CX circuit following a CZ circuit, denoted as a -CZ-CX- circuit,in two-qubit depth at most 5n, for LNN connectivity. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Reference:** + +1. Kutin, S., Moulton, D. P., Smithline, L., *Computation at a distance*, Chicago J. Theor. Comput. Sci., vol. 2007, (2007), [arXiv:quant-ph/0701194](https://arxiv.org/abs/quant-ph/0701194) +2. Dmitri Maslov, Willers Yang, *CNOT circuits need little help to implement arbitrary Hadamard-free Clifford transformations they generate*, [arXiv:2210.16195](https://arxiv.org/abs/2210.16195). + +### synth\_cnot\_phase\_aam + + + +`qiskit.synthesis.synth_cnot_phase_aam(cnots, angles, section_size=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/linear_phase/cnot_phase_synth.py "view source code") + +This function is an implementation of the GraySynth algorithm of Amy, Azimadeh and Mosca. + +GraySynth is a heuristic algorithm from \[1] for synthesizing small parity networks. It is inspired by Gray codes. Given a set of binary strings S (called “cnots” bellow), the algorithm synthesizes a parity network for S by repeatedly choosing an index i to expand and then effectively recursing on the co-factors S\_0 and S\_1, consisting of the strings y in S, with y\_i = 0 or 1 respectively. As a subset S is recursively expanded, CNOT gates are applied so that a designated target bit contains the (partial) parity ksi\_y(x) where y\_i = 1 if and only if y’\_i = 1 for all y’ in S. If S is a singleton \{y’}, then y = y’, hence the target bit contains the value ksi\_y’(x) as desired. + +Notably, rather than uncomputing this sequence of CNOT gates when a subset S is finished being synthesized, the algorithm maintains the invariant that the remaining parities to be computed are expressed over the current state of bits. This allows the algorithm to avoid the ‘backtracking’ inherent in uncomputing-based methods. + +The algorithm is described in detail in section 4 of \[1]. + +**Parameters** + +* **cnots** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*]*) – + + a matrix whose columns are the parities to be synthesized e.g.: + + ```python + [[0, 1, 1, 1, 1, 1], + [1, 0, 0, 1, 1, 1], + [1, 0, 0, 1, 0, 0], + [0, 0, 1, 0, 1, 0]] + ``` + + corresponds to: + + ```python + x1^x2 + x0 + x0^x3 + x0^x1^x2 + x0^x1^x3 + x0^x1 + ``` + +* **angles** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – a list containing all the phase-shift gates which are to be applied, in the same order as in “cnots”. A number is interpreted as the angle of p(angle), otherwise the elements have to be ‘t’, ‘tdg’, ‘s’, ‘sdg’ or ‘z’. + +* **section\_size** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – the size of every section, used in \_lwr\_cnot\_synth(), in the Patel–Markov–Hayes algorithm. section\_size must be a factor of num\_qubits. + +**Returns** + +the decomposed quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – when dimensions of cnots and angles don’t align. + +**References** + +1. Matthew Amy, Parsiad Azimzadeh, and Michele Mosca. *On the controlled-NOT complexity of controlled-NOT–phase circuits.*, Quantum Science and Technology 4.1 (2018): 015002. [arXiv:1712.01859](https://arxiv.org/abs/1712.01859) + +## Permutation Synthesis + +### synth\_permutation\_depth\_lnn\_kms + + + +`qiskit.synthesis.synth_permutation_depth_lnn_kms(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/permutation/permutation_lnn.py "view source code") + +Synthesize a permutation circuit for a linear nearest-neighbor architecture using the Kutin, Moulton, Smithline method. + +This is the permutation synthesis algorithm from [https://arxiv.org/abs/quant-ph/0701194](https://arxiv.org/abs/quant-ph/0701194), Chapter 6. It synthesizes any permutation of n qubits over linear nearest-neighbor architecture using SWAP gates with depth at most n and size at most n(n-1)/2 (where both depth and size are measured with respect to SWAPs). + +**Parameters** + +**pattern** (*Union\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*], np.ndarray]*) – permutation pattern, describing which qubits occupy the positions 0, 1, 2, etc. after applying the permutation. That is, `pattern[k] = m` when the permutation maps qubit `m` to position `k`. As an example, the pattern `[2, 4, 3, 0, 1]` means that qubit `2` goes to position `0`, qubit `4` goes to position `1`, etc. + +**Returns** + +the synthesized quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### synth\_permutation\_basic + + + +`qiskit.synthesis.synth_permutation_basic(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/permutation/permutation_full.py "view source code") + +Synthesize a permutation circuit for a fully-connected architecture using sorting. + +More precisely, if the input permutation is a cycle of length `m`, then this creates a quantum circuit with `m-1` SWAPs (and of depth `m-1`); if the input permutation consists of several disjoint cycles, then each cycle is essentially treated independently. + +**Parameters** + +**pattern** (*Union\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*], np.ndarray]*) – permutation pattern, describing which qubits occupy the positions 0, 1, 2, etc. after applying the permutation. That is, `pattern[k] = m` when the permutation maps qubit `m` to position `k`. As an example, the pattern `[2, 4, 3, 0, 1]` means that qubit `2` goes to position `0`, qubit `4` goes to position `1`, etc. + +**Returns** + +the synthesized quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +### synth\_permutation\_acg + + + +`qiskit.synthesis.synth_permutation_acg(pattern)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/permutation/permutation_full.py "view source code") + +Synthesize a permutation circuit for a fully-connected architecture using the Alon, Chung, Graham method. + +This produces a quantum circuit of depth 2 (measured in the number of SWAPs). + +This implementation is based on the Theorem 2 in the paper “Routing Permutations on Graphs Via Matchings” (1993), available at [https://www.cs.tau.ac.il/\~nogaa/PDFS/r.pdf](https://www.cs.tau.ac.il/~nogaa/PDFS/r.pdf). + +**Parameters** + +**pattern** (*Union\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*], np.ndarray]*) – permutation pattern, describing which qubits occupy the positions 0, 1, 2, etc. after applying the permutation. That is, `pattern[k] = m` when the permutation maps qubit `m` to position `k`. As an example, the pattern `[2, 4, 3, 0, 1]` means that qubit `2` goes to position `0`, qubit `4` goes to position `1`, etc. + +**Returns** + +the synthesized quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +## Clifford Synthesis + +### synth\_clifford\_full + + + +`qiskit.synthesis.synth_clifford_full(clifford, method=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/clifford/clifford_decompose_full.py "view source code") + +Decompose a Clifford operator into a QuantumCircuit. + +For N \<= 3 qubits this is based on optimal CX cost decomposition from reference \[1]. For N > 3 qubits this is done using the general non-optimal greedy compilation routine from reference \[3], which typically yields better CX cost compared to the AG method in \[2]. + +**Parameters** + +* **clifford** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a clifford operator. +* **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Optional, a synthesis method (‘AG’ or ‘greedy’). If set this overrides optimal decomposition for N \<=3 qubits. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**References** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) +2. S. Aaronson, D. Gottesman, *Improved Simulation of Stabilizer Circuits*, Phys. Rev. A 70, 052328 (2004). [arXiv:quant-ph/0406196](https://arxiv.org/abs/quant-ph/0406196) +3. Sergey Bravyi, Shaohan Hu, Dmitri Maslov, Ruslan Shaydulin, *Clifford Circuit Optimization with Templates and Symbolic Pauli Gates*, [arXiv:2105.02291 \[quant-ph\]](https://arxiv.org/abs/2105.02291) + +### synth\_clifford\_ag + + + +`qiskit.synthesis.synth_clifford_ag(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/clifford/clifford_decompose_ag.py "view source code") + +Decompose a Clifford operator into a QuantumCircuit based on Aaronson-Gottesman method. + +**Parameters** + +**clifford** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a clifford operator. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Reference:** + +1. S. Aaronson, D. Gottesman, *Improved Simulation of Stabilizer Circuits*, Phys. Rev. A 70, 052328 (2004). [arXiv:quant-ph/0406196](https://arxiv.org/abs/quant-ph/0406196) + +### synth\_clifford\_bm + + + +`qiskit.synthesis.synth_clifford_bm(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/clifford/clifford_decompose_bm.py "view source code") + +Optimal CX-cost decomposition of a Clifford operator on 2-qubits or 3-qubits into a QuantumCircuit based on Bravyi-Maslov method. + +**Parameters** + +**clifford** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a clifford operator. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if clifford is on more than 3 qubits. + +**Reference:** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) + +### synth\_clifford\_greedy + + + +`qiskit.synthesis.synth_clifford_greedy(clifford)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/clifford/clifford_decompose_greedy.py "view source code") + +Decompose a Clifford operator into a QuantumCircuit based on the greedy Clifford compiler that is described in Appendix A of Bravyi, Hu, Maslov and Shaydulin. + +This method typically yields better CX cost compared to the Aaronson-Gottesman method. + +**Parameters** + +**clifford** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a clifford operator. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if symplectic Gaussian elimination fails. + +**Reference:** + +1. Sergey Bravyi, Shaohan Hu, Dmitri Maslov, Ruslan Shaydulin, *Clifford Circuit Optimization with Templates and Symbolic Pauli Gates*, [arXiv:2105.02291 \[quant-ph\]](https://arxiv.org/abs/2105.02291) + +### synth\_clifford\_layers + + + +`qiskit.synthesis.synth_clifford_layers(cliff, cx_synth_func=, cz_synth_func=, cx_cz_synth_func=None, cz_func_reverse_qubits=False, validate=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/clifford/clifford_decompose_layers.py "view source code") + +Synthesis of a Clifford into layers, it provides a similar decomposition to the synthesis described in Lemma 8 of Bravyi and Maslov. + +For example, a 5-qubit Clifford circuit is decomposed into the following layers: + +```python + ┌─────┐┌─────┐┌────────┐┌─────┐┌─────┐┌─────┐┌─────┐┌────────┐ +q_0: ┤0 ├┤0 ├┤0 ├┤0 ├┤0 ├┤0 ├┤0 ├┤0 ├ + │ ││ ││ ││ ││ ││ ││ ││ │ +q_1: ┤1 ├┤1 ├┤1 ├┤1 ├┤1 ├┤1 ├┤1 ├┤1 ├ + │ ││ ││ ││ ││ ││ ││ ││ │ +q_2: ┤2 S2 ├┤2 CZ ├┤2 CX_dg ├┤2 H2 ├┤2 S1 ├┤2 CZ ├┤2 H1 ├┤2 Pauli ├ + │ ││ ││ ││ ││ ││ ││ ││ │ +q_3: ┤3 ├┤3 ├┤3 ├┤3 ├┤3 ├┤3 ├┤3 ├┤3 ├ + │ ││ ││ ││ ││ ││ ││ ││ │ +q_4: ┤4 ├┤4 ├┤4 ├┤4 ├┤4 ├┤4 ├┤4 ├┤4 ├ + └─────┘└─────┘└────────┘└─────┘└─────┘└─────┘└─────┘└────────┘ +``` + +This decomposition is for the default cz\_synth\_func and cx\_synth\_func functions, with other functions one may see slightly different decomposition. + +**Parameters** + +* **cliff** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a clifford operator. +* **cx\_synth\_func** (*Callable*) – a function to decompose the CX sub-circuit. It gets as input a boolean invertible matrix, and outputs a QuantumCircuit. +* **cz\_synth\_func** (*Callable*) – a function to decompose the CZ sub-circuit. It gets as input a boolean symmetric matrix, and outputs a QuantumCircuit. +* **cx\_cz\_synth\_func** (*Callable*) – optional, a function to decompose both sub-circuits CZ and CX. +* **validate** (*Boolean*) – if True, validates the synthesis process. +* **cz\_func\_reverse\_qubits** (*Boolean*) – True only if cz\_synth\_func is synth\_cz\_depth\_line\_mr, since this function returns a circuit that reverts the order of qubits. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Reference:** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) + +### synth\_clifford\_depth\_lnn + + + +`qiskit.synthesis.synth_clifford_depth_lnn(cliff)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/clifford/clifford_decompose_layers.py "view source code") + +Synthesis of a Clifford into layers for linear-nearest neighbour connectivity. + +The depth of the synthesized n-qubit circuit is bounded by 7\*n+2, which is not optimal. It should be replaced by a better algorithm that provides depth bounded by 7\*n-4 \[3]. + +**Parameters** + +**cliff** ([*Clifford*](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford")) – a clifford operator. + +**Returns** + +a circuit implementation of the Clifford. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Reference:** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) +2. Dmitri Maslov, Martin Roetteler, *Shorter stabilizer circuits via Bruhat decomposition and quantum circuit transformations*, [arXiv:1705.09176](https://arxiv.org/abs/1705.09176). +3. Dmitri Maslov, Willers Yang, *CNOT circuits need little help to implement arbitrary Hadamard-free Clifford transformations they generate*, [arXiv:2210.16195](https://arxiv.org/abs/2210.16195). + +## CNOTDihedral Synthesis + +### synth\_cnotdihedral\_full + + + +`qiskit.synthesis.synth_cnotdihedral_full(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_full.py "view source code") + +Decompose a CNOTDihedral element into a QuantumCircuit. For N \<= 2 qubits this is based on optimal CX cost decomposition from reference \[1]. For N > 2 qubits this is done using the general non-optimal compilation routine from reference \[2]. + +**Parameters** + +**elem** ([*CNOTDihedral*](qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")) – a CNOTDihedral element. + +**Returns** + +a circuit implementation of the CNOTDihedral element. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**References** + +1. Shelly Garion and Andrew W. Cross, *Synthesis of CNOT-Dihedral circuits with optimal number of two qubit gates*, [Quantum 4(369), 2020](https://quantum-journal.org/papers/q-2020-12-07-369/) +2. Andrew W. Cross, Easwar Magesan, Lev S. Bishop, John A. Smolin and Jay M. Gambetta, *Scalable randomised benchmarking of non-Clifford gates*, npj Quantum Inf 2, 16012 (2016). + +### synth\_cnotdihedral\_two\_qubits + + + +`qiskit.synthesis.synth_cnotdihedral_two_qubits(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_two_qubits.py "view source code") + +Decompose a CNOTDihedral element on a single qubit and two qubits into a QuantumCircuit. This decomposition has an optimal number of CX gates. + +**Parameters** + +**elem** ([*CNOTDihedral*](qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")) – a CNOTDihedral element. + +**Returns** + +a circuit implementation of the CNOTDihedral element. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the element in not 1-qubit or 2-qubit CNOTDihedral. + +**Reference:** + +1. Shelly Garion and Andrew W. Cross, *On the structure of the CNOT-Dihedral group*, [arXiv:2006.12042 \[quant-ph\]](https://arxiv.org/abs/2006.12042) + +### synth\_cnotdihedral\_general + + + +`qiskit.synthesis.synth_cnotdihedral_general(elem)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/cnotdihedral/cnotdihedral_decompose_general.py "view source code") + +Decompose a CNOTDihedral element into a QuantumCircuit. + +Decompose a general CNOTDihedral elements. The number of CNOT gates is not necessarily optimal. For a decomposition of a 1-qubit or 2-qubit element, call synth\_cnotdihedral\_two\_qubits. + +**Parameters** + +**elem** ([*CNOTDihedral*](qiskit.quantum_info.CNOTDihedral "qiskit.quantum_info.CNOTDihedral")) – a CNOTDihedral element. + +**Returns** + +a circuit implementation of the CNOTDihedral element. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the element could not be decomposed into a circuit. + +**Reference:** + +1. Andrew W. Cross, Easwar Magesan, Lev S. Bishop, John A. Smolin and Jay M. Gambetta, *Scalable randomised benchmarking of non-Clifford gates*, npj Quantum Inf 2, 16012 (2016). + +## Stabilizer State Synthesis + +### synth\_stabilizer\_layers + + + +`qiskit.synthesis.synth_stabilizer_layers(stab, cz_synth_func=, cz_func_reverse_qubits=False, validate=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/stabilizer/stabilizer_decompose.py "view source code") + +Synthesis of a stabilizer state into layers. + +It provides a similar decomposition to the synthesis described in Lemma 8 of Bravyi and Maslov, without the initial Hadamard-free sub-circuit which do not affect the stabilizer state. + +For example, a 5-qubit stabilizer state is decomposed into the following layers: + +```python + ┌─────┐┌─────┐┌─────┐┌─────┐┌────────┐ +q_0: ┤0 ├┤0 ├┤0 ├┤0 ├┤0 ├ + │ ││ ││ ││ ││ │ +q_1: ┤1 ├┤1 ├┤1 ├┤1 ├┤1 ├ + │ ││ ││ ││ ││ │ +q_2: ┤2 H2 ├┤2 S1 ├┤2 CZ ├┤2 H1 ├┤2 Pauli ├ + │ ││ ││ ││ ││ │ +q_3: ┤3 ├┤3 ├┤3 ├┤3 ├┤3 ├ + │ ││ ││ ││ ││ │ +q_4: ┤4 ├┤4 ├┤4 ├┤4 ├┤4 ├ + └─────┘└─────┘└─────┘└─────┘└────────┘ +``` + +**Parameters** + +* **stab** ([*StabilizerState*](qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState")) – a stabilizer state. +* **cz\_synth\_func** (*Callable*) – a function to decompose the CZ sub-circuit. It gets as input a boolean symmetric matrix, and outputs a QuantumCircuit. +* **validate** (*Boolean*) – if True, validates the synthesis process. +* **cz\_func\_reverse\_qubits** (*Boolean*) – True only if cz\_synth\_func is synth\_cz\_depth\_line\_mr, since this function returns a circuit that reverts the order of qubits. + +**Returns** + +a circuit implementation of the stabilizer state. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the input is not a StabilizerState. + +**Reference:** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) + +### synth\_stabilizer\_depth\_lnn + + + +`qiskit.synthesis.synth_stabilizer_depth_lnn(stab)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/stabilizer/stabilizer_decompose.py "view source code") + +Synthesis of an n-qubit stabilizer state for linear-nearest neighbour connectivity, in 2-qubit depth 2\*n+2 and two distinct CX layers, using CX and phase gates (S, Sdg or Z). + +**Parameters** + +**stab** ([*StabilizerState*](qiskit.quantum_info.StabilizerState "qiskit.quantum_info.StabilizerState")) – a stabilizer state. + +**Returns** + +a circuit implementation of the stabilizer state. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Reference:** + +1. S. Bravyi, D. Maslov, *Hadamard-free circuits expose the structure of the Clifford group*, [arXiv:2003.09412 \[quant-ph\]](https://arxiv.org/abs/2003.09412) +2. Dmitri Maslov, Martin Roetteler, *Shorter stabilizer circuits via Bruhat decomposition and quantum circuit transformations*, [arXiv:1705.09176](https://arxiv.org/abs/1705.09176). + +## Discrete Basis Synthesis + +| | | +| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [`SolovayKitaevDecomposition`](qiskit.synthesis.SolovayKitaevDecomposition "qiskit.synthesis.SolovayKitaevDecomposition")(\[...]) | The Solovay Kitaev discrete decomposition algorithm. | + +### generate\_basic\_approximations + + + +`qiskit.synthesis.generate_basic_approximations(basis_gates, depth, filename=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/discrete_basis/generate_basis_approximations.py "view source code") + +Generates a list of `GateSequence``s with the gates in ``basic_gates`. + +**Parameters** + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")*]*) – The gates from which to create the sequences of gates. +* **depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum depth of the approximations. +* **filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – If provided, the basic approximations are stored in this file. + +**Returns** + +List of `GateSequences` using the gates in `basic_gates`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If `basis_gates` contains an invalid gate identifier. + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[GateSequence] + +## Unitary Synthesis + +Decomposition of general $2^n \times 2^n$ unitary matrices for any number of qubits. + +### qs\_decomposition + + + +`qiskit.synthesis.qs_decomposition(mat, opt_a1=True, opt_a2=True, decomposer_1q=None, decomposer_2q=None, *, _depth=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/qsd.py "view source code") + +Decomposes a unitary matrix into one and two qubit gates using Quantum Shannon Decomposition, + +This decomposition is described in Shende et al. \[1]. + +```python + ┌───┐ ┌───┐ ┌───┐ ┌───┐ + ─┤ ├─ ───────┤ Rz├─────┤ Ry├─────┤ Rz├───── + │ │ ≃ ┌───┐└─┬─┘┌───┐└─┬─┘┌───┐└─┬─┘┌───┐ +/─┤ ├─ /─┤ ├──□──┤ ├──□──┤ ├──□──┤ ├ + └───┘ └───┘ └───┘ └───┘ └───┘ +``` + +The number of CX gates generated with the decomposition without optimizations is, + +$$ +\frac{9}{16} 4^n - \frac{3}{2} 2^n +$$ + +If opt\_a1 = True, the default, the CX count is reduced by, + +$$ +\frac{1}{3} 4^{n - 2} - 1. +$$ + +If opt\_a2 = True, the default, the CX count is reduced by, + +$$ +4^{n-2} - 1. +$$ + +**Parameters** + +* **mat** (*np.ndarray*) – unitary matrix to decompose +* **opt\_a1** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to try optimization A.1 from Shende et al. \[1]. This should eliminate 1 cx per call. If True CZ gates are left in the output. If desired these can be further decomposed to CX. +* **opt\_a2** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – whether to try optimization A.2 from Shende et al. \[1]. This decomposes two qubit unitaries into a diagonal gate and a two cx unitary and reduces overall cx count by $4^{n-2} - 1$. +* **decomposer\_1q** (*Callable\[\[np.ndarray],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – optional 1Q decomposer. If None, uses [`OneQubitEulerDecomposer`](qiskit.synthesis.OneQubitEulerDecomposer "qiskit.synthesis.OneQubitEulerDecomposer"). +* **decomposer\_2q** (*Callable\[\[np.ndarray],* [*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*] | None*) – optional 2Q decomposer. If None, uses [`TwoQubitBasisDecomposer`](qiskit.synthesis.TwoQubitBasisDecomposer "qiskit.synthesis.TwoQubitBasisDecomposer"). + +**Returns** + +Decomposed quantum circuit. + +**Return type** + +[QuantumCircuit](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") + +**Reference:** + +1. Shende, Bullock, Markov, *Synthesis of Quantum Logic Circuits*, [arXiv:0406176 \[quant-ph\]](https://arxiv.org/abs/quant-ph/0406176) + +The Approximate Quantum Compiler is available here: [`qiskit.synthesis.unitary.aqc`](synthesis_aqc#module-qiskit.synthesis.unitary.aqc "qiskit.synthesis.unitary.aqc") + +## One-Qubit Synthesis + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | +| [`OneQubitEulerDecomposer`](qiskit.synthesis.OneQubitEulerDecomposer "qiskit.synthesis.OneQubitEulerDecomposer")(\[basis, use\_dag]) | A class for decomposing 1-qubit unitaries into Euler angle rotations. | + +## Two-Qubit Synthesis + +| | | +| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`TwoQubitBasisDecomposer`](qiskit.synthesis.TwoQubitBasisDecomposer "qiskit.synthesis.TwoQubitBasisDecomposer")(gate\[, ...]) | A class for decomposing 2-qubit unitaries into minimal number of uses of a 2-qubit basis gate. | +| [`XXDecomposer`](qiskit.synthesis.XXDecomposer "qiskit.synthesis.XXDecomposer")(\[basis\_fidelity, euler\_basis, ...]) | A class for optimal decomposition of 2-qubit unitaries into 2-qubit basis gates of XX type (i.e., each locally equivalent to CAN(alpha, 0, 0) for a possibly varying alpha). | + diff --git a/docs/api/qiskit/0.46/synthesis_aqc.md b/docs/api/qiskit/0.46/synthesis_aqc.md new file mode 100644 index 00000000000..821bc5dc1f9 --- /dev/null +++ b/docs/api/qiskit/0.46/synthesis_aqc.md @@ -0,0 +1,168 @@ +--- +title: aqc +description: API reference for qiskit.synthesis.unitary.aqc +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.synthesis.unitary.aqc +--- + + + + + + + +# Approximate Quantum Compiler + + + +`qiskit.synthesis.unitary.aqc` + +Implementation of Approximate Quantum Compiler as described in the paper \[1]. + +## Interface + +The main public interface of this module is reached by passing `unitary_synthesis_method='aqc'` to [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"). This will swap the synthesis method to use `AQCSynthesisPlugin`. The individual classes are: + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| [`AQC`](qiskit.synthesis.unitary.aqc.AQC "qiskit.synthesis.unitary.aqc.AQC")(\[optimizer, seed]) | A generic implementation of the Approximate Quantum Compiler. | +| [`ApproximateCircuit`](qiskit.synthesis.unitary.aqc.ApproximateCircuit "qiskit.synthesis.unitary.aqc.ApproximateCircuit")(num\_qubits\[, name]) | A base class that represents an approximate circuit. | +| [`ApproximatingObjective`](qiskit.synthesis.unitary.aqc.ApproximatingObjective "qiskit.synthesis.unitary.aqc.ApproximatingObjective")() | A base class for an optimization problem definition. | +| [`CNOTUnitCircuit`](qiskit.synthesis.unitary.aqc.CNOTUnitCircuit "qiskit.synthesis.unitary.aqc.CNOTUnitCircuit")(num\_qubits, cnots\[, tol, name]) | A class that represents an approximate circuit based on CNOT unit blocks. | +| [`CNOTUnitObjective`](qiskit.synthesis.unitary.aqc.CNOTUnitObjective "qiskit.synthesis.unitary.aqc.CNOTUnitObjective")(num\_qubits, cnots) | A base class for a problem definition based on CNOT unit. | +| [`DefaultCNOTUnitObjective`](qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective "qiskit.synthesis.unitary.aqc.DefaultCNOTUnitObjective")(num\_qubits, cnots) | A naive implementation of the objective function based on CNOT units. | +| [`FastCNOTUnitObjective`](qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective "qiskit.synthesis.unitary.aqc.FastCNOTUnitObjective")(num\_qubits, cnots) | Implementation of objective function and gradient calculator, which is similar to `DefaultCNOTUnitObjective` but several times faster. | + +## Mathematical Detail + +We are interested in compiling a quantum circuit, which we formalize as finding the best circuit representation in terms of an ordered gate sequence of a target unitary matrix $U\in U(d)$, with some additional hardware constraints. In particular, we look at representations that could be constrained in terms of hardware connectivity, as well as gate depth, and we choose a gate basis in terms of CNOT and rotation gates. We recall that the combination of CNOT and rotation gates is universal in $SU(d)$ and therefore it does not limit compilation. + +To properly define what we mean by best circuit representation, we define the metric as the Frobenius norm between the unitary matrix of the compiled circuit $V$ and the target unitary matrix $U$, i.e., $\|V - U\|_{\mathrm{F}}$. This choice is motivated by mathematical programming considerations, and it is related to other formulations that appear in the literature. Let’s take a look at the problem in more details. + +Let $n$ be the number of qubits and $d=2^n$. Given a CNOT structure $ct$ and a vector of rotation angles $\theta$, the parametric circuit forms a matrix $Vct(\theta)\in SU(d)$. If we are given a target circuit forming a matrix $U\in SU(d)$, then we would like to compute + +$$ +\mathrm{argmax}_{\theta}\frac{1}{d}|\langle Vct(\theta),U\rangle| +$$ + +where the inner product is the Frobenius inner product. Note that $|\langle V,U\rangle|\leq d$ for all unitaries $U$ and $V$, so the objective has range in $[0,1]$. + +Our strategy is to maximize + +$$ +\frac{1}{d}\Re \langle Vct(\theta),U\rangle +$$ + +using its gradient. We will now discuss the specifics by going through an example. + +While the range of $Vct$ is a subset of $SU(d)$ by construction, the target circuit may form a general unitary matrix. However, for any $U\in U(d)$, + +$$ +\frac{\exp(2\pi i k/d)}{\det(U)^{1/d}}U\in SU(d)\text{ for all }k\in\{0,\ldots,d-1\}. +$$ + +Thus, we should normalize the target circuit by its global phase and then approximately compile the normalized circuit. We can add the global phase back in afterwards. + +In the algorithm let $U'$ denote the un-normalized target matrix and $U$ the normalized target matrix. Now that we have $U$, we give the gradient function to the Nesterov’s method optimizer and compute $\theta$. + +To add the global phase back in, we can form the control circuit as + +$$ +\frac{\langle Vct(\theta),U'\rangle}{|\langle Vct(\theta),U'\rangle|}Vct(\theta). +$$ + +Note that while we optimized using Nesterov’s method in the paper, this was for its convergence guarantees, not its speed in practice. It is much faster to use L-BFGS which is used as a default optimizer in this implementation. + +A basic usage of the AQC algorithm should consist of the following steps: + +```python +# Define a target circuit as a unitary matrix +unitary = ... + +# Define a number of qubits for the algorithm, at least 3 qubits +num_qubits = int(round(np.log2(unitary.shape[0]))) + +# Choose a layout of the CNOT structure for the approximate circuit, e.g. ``spin`` for +# a linear layout. +layout = options.get("layout") or "spin" + +# Choose a connectivity type, e.g. ``full`` for full connectivity between qubits. +connectivity = options.get("connectivity") or "full" + +# Define a targeted depth of the approximate circuit in the number of CNOT units. +depth = int(options.get("depth") or 0) + +# Generate a network made of CNOT units +cnots = make_cnot_network( + num_qubits=num_qubits, + network_layout=layout, + connectivity_type=connectivity, + depth=depth +) + +# Create an optimizer to be used by AQC +optimizer = partial(scipy.optimize.minimize, method="L-BFGS-B") + +# Create an instance +aqc = AQC(optimizer) + +# Create a template circuit that will approximate our target circuit +approximate_circuit = CNOTUnitCircuit(num_qubits=num_qubits, cnots=cnots) + +# Create an objective that defines our optimization problem +approximating_objective = DefaultCNOTUnitObjective(num_qubits=num_qubits, cnots=cnots) + +# Run optimization process to compile the unitary +aqc.compile_unitary( + target_matrix=unitary, + approximate_circuit=approximate_circuit, + approximating_objective=approximating_objective +) +``` + +Now `approximate_circuit` is a circuit that approximates the target unitary to a certain degree and can be used instead of the original matrix. + +This uses a helper function, [`make_cnot_network`](#qiskit.synthesis.unitary.aqc.make_cnot_network "qiskit.synthesis.unitary.aqc.make_cnot_network"). + +### make\_cnot\_network + + + +`qiskit.synthesis.unitary.aqc.make_cnot_network(num_qubits, network_layout='spin', connectivity_type='full', depth=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/synthesis/unitary/aqc/cnot_structures.py "view source code") + +Generates a network consisting of building blocks each containing a CNOT gate and possibly some single-qubit ones. This network models a quantum operator in question. Note, each building block has 2 input and outputs corresponding to a pair of qubits. What we actually return here is a chain of indices of qubit pairs shared by every building block in a row. + +**Parameters** + +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – number of qubits. +* **network\_layout** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – type of network geometry, `{"sequ", "spin", "cart", "cyclic_spin", "cyclic_line"}`. +* **connectivity\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – type of inter-qubit connectivity, `{"full", "line", "star"}`. +* **depth** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – depth of the CNOT-network, i.e. the number of layers, where each layer consists of a single CNOT-block; default value will be selected, if `L <= 0`. + +**Returns** + +**A matrix of size `(2, N)` matrix that defines layers in cnot-network, where `N`** + +is either equal `L`, or defined by a concrete type of the network. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if unsupported type of CNOT-network layout or number of qubits or combination of parameters are passed. + +**Return type** + +[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v1.26)") + +One can take advantage of accelerated version of objective function. It implements the same mathematical algorithm as the default one `DefaultCNOTUnitObjective` but runs several times faster. Instantiation of accelerated objective function class is similar to the default case: + +> \# Create an objective that defines our optimization problem approximating\_objective = FastCNOTUnitObjective(num\_qubits=num\_qubits, cnots=cnots) + +The rest of the code in the above example does not change. + +**References** + +**\[1]: Liam Madden, Andrea Simonetto, Best Approximate Quantum Compiling Problems.** + +[arXiv:2106.05649](https://arxiv.org/abs/2106.05649) + diff --git a/docs/api/qiskit/0.46/tools.md b/docs/api/qiskit/0.46/tools.md new file mode 100644 index 00000000000..185c0534fc5 --- /dev/null +++ b/docs/api/qiskit/0.46/tools.md @@ -0,0 +1,140 @@ +--- +title: tools +description: API reference for qiskit.tools +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.tools +--- + + + + + +# Qiskit Tools + + + +`qiskit.tools` + +## Monitoring + +A helper module to get IBM backend information and submitted job status. + +### job\_monitor + + + +`qiskit.tools.job_monitor(job, interval=None, quiet=False, output=<_io.TextIOWrapper name='' mode='w' encoding='utf-8'>, line_discipline='\r')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/tools/monitor/job_monitor.py "view source code") + +Monitor the status of a IBMQJob instance. + +**Parameters** + +* **job** (*BaseJob*) – Job to monitor. +* **interval** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time interval between status queries. +* **quiet** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If True, do not print status messages. +* **output** (*file*) – The file like object to write status messages to. +* **sys.stdout.** (*By default this is*) – +* **line\_discipline** (*string*) – character emitted at start of a line of job monitor output, +* **r.** (*This defaults to*) – + +**Examples** + +```python +from qiskit import BasicAer, transpile +from qiskit.circuit import QuantumCircuit +from qiskit.tools.monitor import job_monitor +sim_backend = BasicAer.get_backend("qasm_simulator") +qc = QuantumCircuit(2, 2) +qc.h(0) +qc.cx(0, 1) +qc.measure_all() +tqc = transpile(qc, sim_backend) +job_sim = sim_backend.run(tqc) +job_monitor(job_sim) +``` + +### backend\_monitor + + + +`qiskit.tools.backend_monitor(backend)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/tools/monitor/overview.py "view source code") + +Monitor a single IBMQ backend. + +**Parameters** + +**backend** (*IBMQBackend*) – Backend to monitor. + +**Raises** + +* [**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – Input is not a IBMQ backend. +* [**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – If qiskit-ibmq-provider is not installed + +Examples: .. code-block:: python + +> from qiskit.providers.ibmq import IBMQ from qiskit.tools.monitor import backend\_monitor provider = IBMQ.get\_provider(hub=’ibm-q’) backend\_monitor(provider.backends.ibmq\_lima) + +### backend\_overview + + + +`qiskit.tools.backend_overview()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/tools/monitor/overview.py "view source code") + +Gives overview information on all the IBMQ backends that are available. + +**Examples** + +```python +from qiskit.providers.ibmq import IBMQ +from qiskit.tools.monitor import backend_overview +provider = IBMQ.get_provider(hub='ibm-q') +backend_overview() +``` + + + + + +### Events ([`qiskit.tools.events`](#module-qiskit.tools.events "qiskit.tools.events")) + +A helper component for publishing and subscribing to events. + + + +`qiskit.tools.events.TextProgressBar(output_handler=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/tools/events/progressbar.py "view source code") + +A simple text-based progress bar. + +**output\_handlerthe handler the progress bar should be written to, default** + +is sys.stdout, another option is sys.stderr + +**Examples** + +The progress bar can be used to track the progress of a parallel\_map. + +```python +import numpy as np +import qiskit.tools.jupyter +from qiskit.tools.parallel import parallel_map +from qiskit.tools.events import TextProgressBar + +TextProgressBar() +%qiskit_progress_bar -t text +parallel_map(np.sin, np.linspace(0,10,100)); +``` + +And it can also be used individually. + +```python +from qiskit.tools.events import TextProgressBar + +iterations = 100 +t = TextProgressBar() +t.start(iterations=iterations) +for i in range(iterations): + # step i of heavy calculation ... + t.update(i + 1) # update progress bar +``` + diff --git a/docs/api/qiskit/0.46/tools_jupyter.md b/docs/api/qiskit/0.46/tools_jupyter.md new file mode 100644 index 00000000000..d3b10441b51 --- /dev/null +++ b/docs/api/qiskit/0.46/tools_jupyter.md @@ -0,0 +1,86 @@ +--- +title: jupyter +description: API reference for qiskit.tools.jupyter +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.tools.jupyter +--- + + + + + + + +# Jupyter Tools + + + +`qiskit.tools.jupyter` + +A Collection of Jupyter magic functions and tools that extend the functionality of Qiskit. + +## Overview of all available backends + +```python +from qiskit.providers.ibmq import IBMQ +import qiskit.tools.jupyter +%matplotlib inline + +IBMQ.load_account() + +%qiskit_backend_overview +``` + +## Detailed information on a single backend + +```python +from qiskit.providers.ibmq import IBMQ +import qiskit.tools.jupyter +%matplotlib inline + +IBMQ.load_account() +provider = IBMQ.get_provider(hub='ibm-q') +backend = provider.get_backend('ibmq_vigo') +backend +``` + +## Load Qiskit Job Watcher + +```python +import qiskit.tools.jupyter +%qiskit_job_watcher +``` + +## HTMLProgressBar + +```python +import numpy as np +from qiskit.tools.parallel import parallel_map +import qiskit.tools.jupyter + +%qiskit_progress_bar +parallel_map(np.sin, np.linspace(0,10,100)); +``` + +## Qiskit version table + +```python +import qiskit.tools.jupyter +%qiskit_version_table +``` + +## Qiskit copyright + +```python +import qiskit.tools.jupyter +%qiskit_copyright +``` + +## Monospaced output + +```python +import qiskit.tools.jupyter +%monospaced_output +``` + diff --git a/docs/api/qiskit/0.46/transpiler.md b/docs/api/qiskit/0.46/transpiler.md new file mode 100644 index 00000000000..508bcf5e9a3 --- /dev/null +++ b/docs/api/qiskit/0.46/transpiler.md @@ -0,0 +1,980 @@ +--- +title: transpiler +description: API reference for qiskit.transpiler +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.transpiler +--- + + + + + + + +# Transpiler + + + +`qiskit.transpiler` + +## Overview + +Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and/or to optimize the circuit for execution on present day noisy quantum systems. + +Most circuits must undergo a series of transformations that make them compatible with a given target device, and optimize them to reduce the effects of noise on the resulting outcomes. Rewriting quantum circuits to match hardware constraints and optimizing for performance can be far from trivial. The flow of logic in the rewriting tool chain need not be linear, and can often have iterative sub-loops, conditional branches, and other complex behaviors. That being said, the standard compilation flow follows the structure given below: + +![../\_images/transpiling\_core\_steps.png](/images/api/qiskit/0.46/transpiling_core_steps.png) + +Qiskit has four pre-built transpilation pipelines available here: [`qiskit.transpiler.preset_passmanagers`](transpiler_preset#module-qiskit.transpiler.preset_passmanagers "qiskit.transpiler.preset_passmanagers"). Unless the reader is familiar with quantum circuit optimization methods and their usage, it is best to use one of these ready-made routines. By default the preset pass managers are composed of six stages: + +1. `init` - This stage runs any initial passes that are required before we start embedding the circuit to the backend. This typically involves unrolling custom instructions and converting the circuit to all 1 and 2 qubit gates. +2. `layout` - This stage applies a layout, mapping the virtual qubits in the circuit to the physical qubits on a backend. See [Layout Stage](#layout-stage) for more details. +3. `routing` - This stage runs after a layout has been applied and will inject gates (i.e. swaps) into the original circuit to make it compatible with the backend’s connectivity. See [Routing Stage](#routing-stage) for more details. +4. `translation` - This stage translates the gates in the circuit to the target backend’s basis set. See [Translation Stage](#translation-stage) for more details. +5. `optimization` - This stage runs the main optimization loop repeatedly until a condition (such as fixed depth) is reached. See [Optimization Stage](#optimization-stage) for more details. +6. `scheduling` - This stage is for any hardware-aware scheduling passes. See [Scheduling Stage](#scheduling-stage) for more details. + +When using [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"), the implementation of each stage can be modified with the `*_method` arguments (e.g. `layout_method`). These can be set to one of the built-in methods and can also refer to available external plugins. See [`qiskit.transpiler.preset_passmanagers.plugin`](transpiler_plugins#module-qiskit.transpiler.preset_passmanagers.plugin "qiskit.transpiler.preset_passmanagers.plugin") for details on this plugin interface. + + + +## Working with Preset Pass Managers + +Qiskit includes functions to build preset [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") objects. These preset passmanagers are used by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function for each optimization level. There are 4 optimization levels ranging from 0 to 3, where higher optimization levels take more time and computational effort but may yield a more optimal circuit. Optimization level 0 is intended for device characterization experiments and, as such, only maps the input circuit to the constraints of the target backend, without performing any optimizations. Optimization level 3 spends the most effort to optimize the circuit. However, as many of the optimization techniques in the transpiler are heuristic based, spending more computational effort does not always result in an improvement in the quality of the output circuit. + +If you’d like to work directly with a preset pass manager you can use the [`generate_preset_pass_manager()`](transpiler_preset#qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager "qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager") function to easily generate one. For example: + +```python +from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager +from qiskit.providers.fake_provider import FakeLagosV2 + +backend = FakeLagosV2() +pass_manager = generate_preset_pass_manager(3, backend) +``` + +which will generate a [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager") object for optimization level 3 targeting the [`FakeLagosV2`](qiskit.providers.fake_provider.FakeLagosV2 "qiskit.providers.fake_provider.FakeLagosV2") backend (equivalent to what is used internally by [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") with `backend=FakeLagosV2()` and `optimization_level=3`). You can use this just like you would any other [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager"). However, because it is a [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager") it also makes it easy to compose and/or replace stages of the pipeline. For example, if you wanted to run a custom scheduling stage using dynamical decoupling (via the [`PadDynamicalDecoupling`](qiskit.transpiler.passes.PadDynamicalDecoupling "qiskit.transpiler.passes.PadDynamicalDecoupling") pass) and also add initial logical optimization prior to routing, you would do something like (building off the previous example): + +```python +import numpy as np +from qiskit.circuit.library import HGate, PhaseGate, RXGate, TdgGate, TGate, XGate +from qiskit.transpiler import PassManager +from qiskit.transpiler.passes import ( + ALAPScheduleAnalysis, + CXCancellation, + InverseCancellation, + PadDynamicalDecoupling, +) + +dd_sequence = [XGate(), XGate()] +scheduling_pm = PassManager( + [ + ALAPScheduleAnalysis(target=backend.target), + PadDynamicalDecoupling(target=backend.target, dd_sequence=dd_sequence), + ] +) +inverse_gate_list = [ + HGate(), + (RXGate(np.pi / 4), RXGate(-np.pi / 4)), + (PhaseGate(np.pi / 4), PhaseGate(-np.pi / 4)), + (TGate(), TdgGate()), +] +logical_opt = PassManager( + [ + CXCancellation(), + InverseCancellation(inverse_gate_list), + ] +) + + +# Add pre-layout stage to run extra logical optimization +pass_manager.pre_layout = logical_opt +# Set scheduling stage to custom pass manager +pass_manager.scheduling = scheduling_pm +``` + +Now, when the staged pass manager is run via the [`run()`](qiskit.transpiler.StagedPassManager#run "qiskit.transpiler.StagedPassManager.run") method, the `logical_opt` pass manager will be called before the `layout` stage, and the `scheduling_pm` pass manager will be used for the `scheduling` stage instead of the default. + +## Custom Pass Managers + +In addition to modifying preset pass managers, it is also possible to construct a pass manager to build an entirely custom pipeline for transforming input circuits. You can use the [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager") class directly to do this. You can define arbitrary stage names and populate them with a [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") instance. For example, the following code creates a new [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager") that has 2 stages, `init` and `translation`.: + +```python +from qiskit.transpiler.passes import ( + UnitarySynthesis, + Collect2qBlocks, + ConsolidateBlocks, + UnitarySynthesis, + Unroll3qOrMore, +) +from qiskit.transpiler import PassManager, StagedPassManager + +basis_gates = ["rx", "ry", "rxx"] +init = PassManager([UnitarySynthesis(basis_gates, min_qubits=3), Unroll3qOrMore()]) +translate = PassManager( + [ + Collect2qBlocks(), + ConsolidateBlocks(basis_gates=basis_gates), + UnitarySynthesis(basis_gates), + ] +) + +staged_pm = StagedPassManager( + stages=["init", "translation"], init=init, translation=translate +) +``` + +There is no limit on the number of stages you can put in a [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). + +The [Stage Generator Functions](transpiler_preset#stage-generators) may be useful for the construction of custom `generate_embed_passmanager` generates a [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") to “embed” a selected initial [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") from a layout pass to the specified target device. + +## Representing Quantum Computers + +To be able to compile a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") for a specific backend, the transpiler needs a specialized representation of that backend, including its constraints, instruction set, qubit properties, and more, to be able to compile and optimize effectively. While the [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") class defines an interface for querying and interacting with backends, its scope is larger than just the transpiler’s needs including managing job submission and potentially interfacing with remote services. The specific information needed by the transpiler is described by the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class + +For example, to construct a simple [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object, one can iteratively add descriptions of the instructions it supports: + +```python +from qiskit.circuit import Parameter, Measure +from qiskit.transpiler import Target, InstructionProperties +from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate + +target = Target(num_qubits=3) +target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)}) +target.add_instruction( + UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')), + { + (0,): InstructionProperties(error=.00001, duration=5e-8), + (1,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RZGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RYGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RXGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + CZGate(), + { + (1, 2): InstructionProperties(error=.0001, duration=5e-7), + (2, 0): InstructionProperties(error=.0001, duration=5e-7) + } +) +target.add_instruction( + Measure(), + { + (0,): InstructionProperties(error=.001, duration=5e-5), + (1,): InstructionProperties(error=.002, duration=6e-5), + (2,): InstructionProperties(error=.2, duration=5e-7) + } +) +print(target) +``` + +```python +Target +Number of qubits: 3 +Instructions: + cx + (0, 1): + Duration: 5e-07 sec. + Error Rate: 0.0001 + u + (0,): + Duration: 5e-08 sec. + Error Rate: 1e-05 + (1,): + Duration: 6e-08 sec. + Error Rate: 2e-05 + rz + (1,): + Duration: 5e-08 sec. + Error Rate: 1e-05 + (2,): + Duration: 6e-08 sec. + Error Rate: 2e-05 + ry + (1,): + Duration: 5e-08 sec. + Error Rate: 1e-05 + (2,): + Duration: 6e-08 sec. + Error Rate: 2e-05 + rx + (1,): + Duration: 5e-08 sec. + Error Rate: 1e-05 + (2,): + Duration: 6e-08 sec. + Error Rate: 2e-05 + cz + (1, 2): + Duration: 5e-07 sec. + Error Rate: 0.0001 + (2, 0): + Duration: 5e-07 sec. + Error Rate: 0.0001 + measure + (0,): + Duration: 5e-05 sec. + Error Rate: 0.001 + (1,): + Duration: 6e-05 sec. + Error Rate: 0.002 + (2,): + Duration: 5e-07 sec. + Error Rate: 0.2 +``` + +This [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") represents a 3 qubit backend that supports [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") between qubits 0 and 1, [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate") on qubits 0 and 1, [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate"), [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate"), and [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.RYGate") on qubits 1 and 2, [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate") between qubits 1 and 2, and qubits 2 and 0, and [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure") on all qubits. + +There are also specific data structures to represent a specific subset of information from the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"). For example, the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") class is used to solely represent the connectivity constraints of a backend as a directed graph. A coupling map can be generated from a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") using the [`Target.build_coupling_map()`](qiskit.transpiler.Target#build_coupling_map "qiskit.transpiler.Target.build_coupling_map") method. These data structures typically pre-date the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") class but are still used by some transpiler passes that do not work natively with a [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") instance yet or when dealing with backends that aren’t using the latest [`BackendV2`](qiskit.providers.BackendV2 "qiskit.providers.BackendV2") interface. + +For example, if we wanted to visualize the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") for the example 3 qubit [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") above: + +```python +from qiskit.circuit import Parameter, Measure +from qiskit.transpiler import Target, InstructionProperties +from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate + +target = Target(num_qubits=3) +target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)}) +target.add_instruction( + UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')), + { + (0,): InstructionProperties(error=.00001, duration=5e-8), + (1,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RZGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RYGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RXGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + CZGate(), + { + (1, 2): InstructionProperties(error=.0001, duration=5e-7), + (2, 0): InstructionProperties(error=.0001, duration=5e-7) + } +) +target.add_instruction( + Measure(), + { + (0,): InstructionProperties(error=.001, duration=5e-5), + (1,): InstructionProperties(error=.002, duration=6e-5), + (2,): InstructionProperties(error=.2, duration=5e-7) + } +) + +target.build_coupling_map().draw() +``` + +This shows the global connectivity of the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") which is the combination of the supported qubits for [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") and [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate"). To see the individual connectivity, you can pass the operation name to `CouplingMap.build_coupling_map()`: + +```python +from qiskit.circuit import Parameter, Measure +from qiskit.transpiler import Target, InstructionProperties +from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate + +target = Target(num_qubits=3) +target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)}) +target.add_instruction( + UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')), + { + (0,): InstructionProperties(error=.00001, duration=5e-8), + (1,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RZGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RYGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RXGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + CZGate(), + { + (1, 2): InstructionProperties(error=.0001, duration=5e-7), + (2, 0): InstructionProperties(error=.0001, duration=5e-7) + } +) +target.add_instruction( + Measure(), + { + (0,): InstructionProperties(error=.001, duration=5e-5), + (1,): InstructionProperties(error=.002, duration=6e-5), + (2,): InstructionProperties(error=.2, duration=5e-7) + } +) + +target.build_coupling_map('cx').draw() +``` + +```python +from qiskit.circuit import Parameter, Measure +from qiskit.transpiler import Target, InstructionProperties +from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate + +target = Target(num_qubits=3) +target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)}) +target.add_instruction( + UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')), + { + (0,): InstructionProperties(error=.00001, duration=5e-8), + (1,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RZGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RYGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + RXGate(Parameter('theta')), + { + (1,): InstructionProperties(error=.00001, duration=5e-8), + (2,): InstructionProperties(error=.00002, duration=6e-8) + } +) +target.add_instruction( + CZGate(), + { + (1, 2): InstructionProperties(error=.0001, duration=5e-7), + (2, 0): InstructionProperties(error=.0001, duration=5e-7) + } +) +target.add_instruction( + Measure(), + { + (0,): InstructionProperties(error=.001, duration=5e-5), + (1,): InstructionProperties(error=.002, duration=6e-5), + (2,): InstructionProperties(error=.2, duration=5e-7) + } +) + +target.build_coupling_map('cz').draw() +``` + + + +## Transpiler Stage Details + +Below are a description of the default transpiler stages and the problems they solve. The default passes used for each stage are described, but the specifics are configurable via the `*_method` keyword arguments for the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") and [`generate_preset_pass_manager()`](transpiler_preset#qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager "qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager") functions which can be used to override the methods described in this section. + + + +### Translation Stage + +When writing a quantum circuit you are free to use any quantum gate (unitary operator) that you like, along with a collection of non-gate operations such as qubit measurements and reset operations. However, most quantum devices only natively support a handful of quantum gates and non-gate operations. The allowed instructions for a given backend can be found by querying the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") for the devices: + +```python +from qiskit.providers.fake_provider import FakeVigoV2 +backend = FakeVigoV2() + +print(backend.target) +``` + +Every quantum circuit run on the target device must be expressed using only these instructions. For example, to run a simple phase estimation circuit: + +```python +import numpy as np +from qiskit import QuantumCircuit +from qiskit.providers.fake_provider import FakeVigoV2 + +backend = FakeVigoV2() + +qc = QuantumCircuit(2, 1) + +qc.h(0) +qc.x(1) +qc.cp(np.pi/4, 0, 1) +qc.h(0) +qc.measure([0], [0]) +qc.draw(output='mpl') +``` + +![../\_images/transpiler-4.png](/images/api/qiskit/0.46/transpiler-4.png) + +We have $H$, $X$, and controlled-$P$ gates, none of which are in our device’s basis gate set, and thus must be translated. This translation is taken care of for us in the `qiskit.execute()` function. However, we can transpile the circuit to show what it will look like in the native gate set of the target IBM Quantum device (the [`FakeVigoV2`](qiskit.providers.fake_provider.FakeVigoV2 "qiskit.providers.fake_provider.FakeVigoV2") backend is a fake backend that models the historical IBM Vigo 5 qubit device for test purposes): + +```python +from qiskit import transpile +from qiskit import QuantumCircuit +from qiskit.providers.fake_provider import FakeVigoV2 + +backend = FakeVigoV2() + +qc = QuantumCircuit(2, 1) + +qc.h(0) +qc.x(1) +qc.cp(np.pi/4, 0, 1) +qc.h(0) +qc.measure([0], [0]) + +qc_basis = transpile(qc, backend) +qc_basis.draw(output='mpl') +``` + +![../\_images/transpiler-5.png](/images/api/qiskit/0.46/transpiler-5.png) + +A few things to highlight. First, the circuit has gotten longer with respect to the original. This can be verified by checking the depth of both circuits: + +```python +print('Original depth:', qc.depth(), 'Decomposed Depth:', qc_basis.depth()) +``` + +```python +Original depth: 4 Decomposed Depth: 10 +``` + +Second, although we had a single controlled gate, the fact that it was not in the basis set means that, when expanded, it requires more than a single [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") to implement. All said, unrolling to the basis set of gates leads to an increase in the depth of a quantum circuit and the number of gates. + +It is important to highlight two special cases: + +1. If A swap gate is not a native gate and must be decomposed this requires three CNOT gates: + + ```python + from qiskit.providers.fake_provider import FakeVigoV2 + backend = FakeVigoV2() + + print(backend.operation_names) + ``` + + ```python + ['id', 'rz', 'sx', 'x', 'cx', 'measure', 'delay'] + ``` + + As a product of three CNOT gates, swap gates are expensive operations to perform on noisy quantum devices. However, such operations are usually necessary for embedding a circuit into the limited gate connectivities of many devices. Thus, minimizing the number of swap gates in a circuit is a primary goal in the transpilation process. + +2. A Toffoli, or controlled-controlled-not gate (`ccx`), is a three-qubit gate. Given that our basis gate set includes only single- and two-qubit gates, it is obvious that this gate must be decomposed. This decomposition is quite costly: + + ```python + from qiskit.circuit import QuantumCircuit + + ccx_circ = QuantumCircuit(3) + ccx_circ.ccx(0, 1, 2) + ccx_circ.decompose().draw(output='mpl') + ``` + + ![../\_images/transpiler-6.png](/images/api/qiskit/0.46/transpiler-6.png) + + For every Toffoli gate in a quantum circuit, the hardware may execute up to six CNOT gates, and a handful of single-qubit gates. From this example, it should be clear that any algorithm that makes use of multiple Toffoli gates will end up as a circuit with large depth and will therefore be appreciably affected by noise and gate errors. + + + +### Layout Stage + +Quantum circuits are abstract entities whose qubits are “virtual” representations of actual qubits used in computations. We need to be able to map these virtual qubits in a one-to-one manner to the “physical” qubits in an actual quantum device. + +![../\_images/mapping.png](/images/api/qiskit/0.46/mapping.png) + +By default, qiskit will do this mapping for you. The choice of mapping depends on the properties of the circuit, the particular device you are targeting, and the optimization level that is chosen. The choice of initial layout is extremely important for minimizing the number of swap operations needed to map the input circuit onto the device topology and for minimizing the loss due to non-uniform noise properties across a device. Due to the importance of this stage, the preset pass managers try a few different methods to find the best layout. Typically this involves 2 steps: first, trying to find a “perfect” layout (a layout which does not require any swap operations), and then, a heuristic pass that tries to find the best layout to use if a perfect layout cannot be found. There are 2 passes typically used for the first stage: + +* [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout"): Models layout selection as a subgraph isomorphism problem and tries to find a subgraph of the connectivity graph that is isomorphic to the graph of 2 qubit interactions in the circuit. If more than one isomorphic mapping is found a scoring heuristic is run to select the mapping which would result in the lowest average error when executing the circuit. +* [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout"): Maps each virtual qubit to the same numbered physical qubit on the device, i.e. `[0,1,2,3,4]` -> `[0,1,2,3,4]`. This is historical behavior used only in `optimization_level=1` to try to find a perfect layout. If it fails to do so, [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout") is tried next. + +Next, for the heuristic stage, 2 passes are used by default: + +* [`SabreLayout`](qiskit.transpiler.passes.SabreLayout "qiskit.transpiler.passes.SabreLayout"): Selects a layout by starting from an initial random layout and then repeatedly running a routing algorithm (by default [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap")) both forward and backward over the circuit, using the permutation caused by swap insertions to adjust that initial random layout. For more details you can refer to the paper describing the algorithm: [arXiv:1809.02573](https://arxiv.org/abs/1809.02573) [`SabreLayout`](qiskit.transpiler.passes.SabreLayout "qiskit.transpiler.passes.SabreLayout") is used to select a layout if a perfect layout isn’t found for optimization levels 1, 2, and 3. +* [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout"): Always used for the layout at optimization level 0. +* [`DenseLayout`](qiskit.transpiler.passes.DenseLayout "qiskit.transpiler.passes.DenseLayout"): Finds the sub-graph of the device with greatest connectivity that has the same number of qubits as the circuit. Used for optimization level 1 if there are control flow operations (such as [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp")) present in the circuit. + +Let’s see what layouts are automatically picked at various optimization levels. The circuits returned by [`qiskit.compiler.transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") are annotated with this initial layout information, and we can view this layout selection graphically using [`qiskit.visualization.plot_circuit_layout()`](qiskit.visualization.plot_circuit_layout "qiskit.visualization.plot_circuit_layout"): + +```python +from qiskit import QuantumCircuit, transpile +from qiskit.visualization import plot_circuit_layout +from qiskit.providers.fake_provider import FakeVigo +backend = FakeVigo() + +ghz = QuantumCircuit(3, 3) +ghz.h(0) +ghz.cx(0,range(1,3)) +ghz.barrier() +ghz.measure(range(3), range(3)) +ghz.draw(output='mpl') +``` + +![../\_images/transpiler-7.png](/images/api/qiskit/0.46/transpiler-7.png) + +* **Layout Using Optimization Level 0** + + > ```python + > from qiskit import QuantumCircuit, transpile + > from qiskit.visualization import plot_circuit_layout + > from qiskit.providers.fake_provider import FakeVigo + > backend = FakeVigo() + > + > ghz = QuantumCircuit(3, 3) + > ghz.h(0) + > ghz.cx(0,range(1,3)) + > ghz.barrier() + > ghz.measure(range(3), range(3)) + > + > new_circ_lv0 = transpile(ghz, backend=backend, optimization_level=0) + > plot_circuit_layout(new_circ_lv0, backend) + > ``` + > + > ![../\_images/transpiler-8.png](/images/api/qiskit/0.46/transpiler-8.png) + +* **Layout Using Optimization Level 3** + + > ```python + > from qiskit import QuantumCircuit, transpile + > from qiskit.visualization import plot_circuit_layout + > from qiskit.providers.fake_provider import FakeVigo + > backend = FakeVigo() + > + > ghz = QuantumCircuit(3, 3) + > ghz.h(0) + > ghz.cx(0,range(1,3)) + > ghz.barrier() + > ghz.measure(range(3), range(3)) + > + > new_circ_lv3 = transpile(ghz, backend=backend, optimization_level=3) + > plot_circuit_layout(new_circ_lv3, backend) + > ``` + > + > ![../\_images/transpiler-9.png](/images/api/qiskit/0.46/transpiler-9.png) + +It is possible to override automatic layout selection by specifying an initial layout. To do so we can pass a list of integers to [`qiskit.compiler.transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") via the initial\_layout keyword argument, where the index labels the virtual qubit in the circuit and the corresponding value is the label for the physical qubit to map onto: + +```python +from qiskit import QuantumCircuit, transpile +from qiskit.visualization import plot_circuit_layout +from qiskit.providers.fake_provider import FakeVigo +backend = FakeVigo() + +ghz = QuantumCircuit(3, 3) +ghz.h(0) +ghz.cx(0,range(1,3)) +ghz.barrier() +ghz.measure(range(3), range(3)) + +# Virtual -> physical +# 0 -> 3 +# 1 -> 4 +# 2 -> 2 + +my_ghz = transpile(ghz, backend, initial_layout=[3, 4, 2]) +plot_circuit_layout(my_ghz, backend) +``` + +![../\_images/transpiler-10.png](/images/api/qiskit/0.46/transpiler-10.png) + + + +### Routing Stage + +In order to implement a 2-qubit gate between qubits in a quantum circuit that are not directly connected on a quantum device, one or more swap gates must be inserted into the circuit to move the qubit states around until they are adjacent on the device gate map. Each swap gate typically represents an expensive and noisy operation to perform. Thus, finding the minimum number of swap gates needed to map a circuit onto a given device, is an important step (if not the most important) in the whole execution process. + +However, as with many important things in life, finding the optimal swap mapping is hard. In fact it is in a class of problems called NP-hard, and is thus prohibitively expensive to compute for all but the smallest quantum devices and input circuits. To get around this, by default Qiskit uses a stochastic heuristic algorithm called [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap") to compute a good, but not necessarily optimal swap mapping. The use of a stochastic method means the circuits generated by [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") (or [`execute()`](execute#qiskit.execute_function.execute "qiskit.execute_function.execute") that calls [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") internally) are not guaranteed to be the same over repeated runs. Indeed, running the same circuit repeatedly will in general result in a distribution of circuit depths and gate counts at the output. + +In order to highlight this, we run a GHZ circuit 100 times, using a “bad” (disconnected) initial\_layout: + +![../\_images/transpiler-11.png](/images/api/qiskit/0.46/transpiler-11.png) + +```python +import matplotlib.pyplot as plt +from qiskit import QuantumCircuit, transpile +from qiskit.providers.fake_provider import FakeAuckland +backend = FakeAuckland() + +ghz = QuantumCircuit(15) +ghz.h(0) +ghz.cx(0, range(1, 15)) + +depths = [] +for _ in range(100): + depths.append( + transpile( + ghz, + backend, + layout_method='trivial' # Fixed layout mapped in circuit order + ).depth() + ) + +plt.figure(figsize=(8, 6)) +plt.hist(depths, align='left', color='#AC557C') +plt.xlabel('Depth', fontsize=14) +plt.ylabel('Counts', fontsize=14); +``` + +![../\_images/transpiler-12.png](/images/api/qiskit/0.46/transpiler-12.png) + +This distribution is quite wide, signaling the difficulty the swap mapper is having in computing the best mapping. Most circuits will have a distribution of depths, perhaps not as wide as this one, due to the stochastic nature of the default swap mapper. Of course, we want the best circuit we can get, especially in cases where the depth is critical to success or failure. The [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap") pass will by default by run its algorithm in parallel with multiple seed values and select the output which uses the fewest swaps. If you would like to increase the number of trials [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap") runs you can refer to [Working with Preset Pass Managers](#working-with-preset-pass-managers) and modify the `routing` stage with a custom instance of [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap") with a larger value for the `trials` argument. + +Typically, following the swap mapper, the routing stage in the preset pass managers also includes running the [`VF2PostLayout`](qiskit.transpiler.passes.VF2PostLayout "qiskit.transpiler.passes.VF2PostLayout") pass. As its name implies, [`VF2PostLayout`](qiskit.transpiler.passes.VF2PostLayout "qiskit.transpiler.passes.VF2PostLayout") uses the same basic algorithm as [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout"), but instead of using it to find a perfect initial layout, it is designed to run after mapping and try to find a layout on qubits with lower error rates which will result in better output fidelity when running the circuit. The details of this algorithm are described in [arXiv:2209.15512](https://arxiv.org/abs/2209.15512). + + + +### Optimization Stage + +Decomposing quantum circuits into the basis gate set of the target device, and the addition of swap gates needed to match hardware topology, conspire to increase the depth and gate count of quantum circuits. Fortunately many routines for optimizing circuits by combining or eliminating gates exist. In some cases these methods are so effective the output circuits have lower depth than the inputs. In other cases, not much can be done, and the computation may be difficult to perform on noisy devices. Different gate optimizations are turned on with different `optimization_level` values. Below we show the benefits gained from setting the optimization level higher: + + + The output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") varies due to the stochastic swap mapper. So the numbers below will likely change each time you run the code. + + +![../\_images/transpiler-13.png](/images/api/qiskit/0.46/transpiler-13.png) + +```python +import matplotlib.pyplot as plt +from qiskit import QuantumCircuit, transpile +from qiskit.providers.fake_provider import FakeAuckland +backend = FakeAuckland() + +ghz = QuantumCircuit(15) +ghz.h(0) +ghz.cx(0, range(1, 15)) + +depths = [] +gate_counts = [] +non_local_gate_counts = [] +levels = [str(x) for x in range(4)] +for level in range(4): + circ = transpile(ghz, backend, optimization_level=level) + depths.append(circ.depth()) + gate_counts.append(sum(circ.count_ops().values())) + non_local_gate_counts.append(circ.num_nonlocal_gates()) +fig, (ax1, ax2) = plt.subplots(2, 1) +ax1.bar(levels, depths, label='Depth') +ax1.set_xlabel("Optimization Level") +ax1.set_ylabel("Depth") +ax1.set_title("Output Circuit Depth") +ax2.bar(levels, gate_counts, label='Number of Circuit Operations') +ax2.bar(levels, non_local_gate_counts, label='Number of non-local gates') +ax2.set_xlabel("Optimization Level") +ax2.set_ylabel("Number of gates") +ax2.legend() +ax2.set_title("Number of output circuit gates") +fig.tight_layout() +plt.show() +``` + +![../\_images/transpiler-14.png](/images/api/qiskit/0.46/transpiler-14.png) + + + +### Scheduling Stage + +After the circuit has been translated to the target basis, mapped to the device, and optimized, a scheduling phase can be applied to optionally account for all the idle time in the circuit. At a high level, the scheduling can be thought of as inserting delays into the circuit to account for idle time on the qubits between the execution of instructions. For example, if we start with a circuit such as: + +![../\_images/transpiler-15.png](/images/api/qiskit/0.46/transpiler-15.png) + +we can then call [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") on it with `scheduling_method` set: + +```python +from qiskit import QuantumCircuit, transpile +from qiskit.providers.fake_provider import FakeBoeblingen + +backend = FakeBoeblingen() + +ghz = QuantumCircuit(5) +ghz.h(0) +ghz.cx(0,range(1,5)) + +circ = transpile(ghz, backend, scheduling_method="asap") +circ.draw(output='mpl') +``` + +![../\_images/transpiler-16.png](/images/api/qiskit/0.46/transpiler-16.png) + +You can see here that the transpiler inserted [`Delay`](qiskit.circuit.Delay "qiskit.circuit.Delay") instructions to account for idle time on each qubit. To get a better idea of the timing of the circuit we can also look at it with the `timeline.draw()` function: + +![../\_images/transpiler-17.png](/images/api/qiskit/0.46/transpiler-17.png) + +The scheduling of a circuit involves two parts: analysis and constraint mapping, followed by a padding pass. The first part requires running a scheduling analysis pass such as `ALAPSchedulingAnalysis` or `ASAPSchedulingAnalysis` which analyzes the circuit and records the start time of each instruction in the circuit using a scheduling algorithm (“as late as possible” for `ALAPSchedulingAnalysis` and “as soon as possible” for `ASAPSchedulingAnalysis`) in the property set. Once the circuit has an initial scheduling, additional passes can be run to account for any timing constraints on the target backend, such as alignment constraints. This is typically done with the [`ConstrainedReschedule`](qiskit.transpiler.passes.ConstrainedReschedule "qiskit.transpiler.passes.ConstrainedReschedule") pass which will adjust the scheduling set in the property set to the constraints of the target backend. Once all the scheduling and adjustments/rescheduling are finished, a padding pass, such as [`PadDelay`](qiskit.transpiler.passes.PadDelay "qiskit.transpiler.passes.PadDelay") or [`PadDynamicalDecoupling`](qiskit.transpiler.passes.PadDynamicalDecoupling "qiskit.transpiler.passes.PadDynamicalDecoupling") is run to insert the instructions into the circuit, which completes the scheduling. + +#### Scheduling Analysis with control flow instructions + +When running scheduling analysis passes on a circuit, you must keep in mind that there are additional constraints on classical conditions and control flow instructions. This section covers the details of these additional constraints that any scheduling pass will need to account for. + +##### Topological node ordering in scheduling + +The DAG representation of `QuantumCircuit` respects the node ordering in the classical register wires, though theoretically two conditional instructions conditioned on the same register could commute, i.e. read-access to the classical register doesn’t change its state. + +```python +qc = QuantumCircuit(2, 1) +qc.delay(100, 0) +qc.x(0).c_if(0, True) +qc.x(1).c_if(0, True) +``` + +The scheduler SHOULD comply with the above topological ordering policy of the DAG circuit. Accordingly, the asap-scheduled circuit will become + +```python + ┌────────────────┐ ┌───┐ +q_0: ┤ Delay(100[dt]) ├───┤ X ├────────────── + ├────────────────┤ └─╥─┘ ┌───┐ +q_1: ┤ Delay(100[dt]) ├─────╫────────┤ X ├─── + └────────────────┘ ║ └─╥─┘ + ┌────╨────┐┌────╨────┐ +c: 1/══════════════════╡ c_0=0x1 ╞╡ c_0=0x1 ╞ + └─────────┘└─────────┘ +``` + +Note that this scheduling might be inefficient in some cases, because the second conditional operation could start without waiting for the 100 dt delay. However, any additional optimization should be done in a different pass, not to break the topological ordering of the original circuit. + +##### Realistic control flow scheduling (respecting microarchitecture) + +In the dispersive QND readout scheme, the qubit (Q) is measured by sending a microwave stimulus, followed by a resonator ring-down (depopulation). This microwave signal is recorded in the buffer memory (B) with the hardware kernel, then a discriminated (D) binary value is moved to the classical register (C). A sequence from t0 to t1 of the measure instruction interval could be modeled as follows: + +```python +Q ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ +B ░░▒▒▒▒▒▒▒▒░░░░░░░░░ +D ░░░░░░░░░░▒▒▒▒▒▒░░░ +C ░░░░░░░░░░░░░░░░▒▒░ +``` + +However, the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") representation is not accurate enough to represent this model. In the circuit representation, the corresponding [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") is occupied by the stimulus microwave signal during the first half of the interval, and the [`Clbit`](qiskit.circuit.Clbit "qiskit.circuit.Clbit") is only occupied at the very end of the interval. + +The lack of precision representing the physical model may induce edge cases in the scheduling: + +```python + ┌───┐ +q_0: ───┤ X ├────── + └─╥─┘ ┌─┐ +q_1: ─────╫─────┤M├ + ┌────╨────┐└╥┘ +c: 1/╡ c_0=0x1 ╞═╩═ + └─────────┘ 0 +``` + +In this example, a user may intend to measure the state of `q_1` after the [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") is applied to `q_0`. This is the correct interpretation from the viewpoint of topological node ordering, i.e. The [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") node comes in front of the [`Measure`](qiskit.circuit.library.Measure "qiskit.circuit.library.Measure") node. However, according to the measurement model above, the data in the register is unchanged during the application of the stimulus, so two nodes are simultaneously operated. If one tries to alap-schedule this circuit, it may return following circuit: + +```python + ┌────────────────┐ ┌───┐ +q_0: ┤ Delay(500[dt]) ├───┤ X ├────── + └────────────────┘ └─╥─┘ ┌─┐ +q_1: ───────────────────────╫─────┤M├ + ┌────╨────┐└╥┘ +c: 1/══════════════════╡ c_0=0x1 ╞═╩═ + └─────────┘ 0 +``` + +Note that there is no delay on the `q_1` wire, and the measure instruction immediately starts after t=0, while the conditional gate starts after the delay. It looks like the topological ordering between the nodes is flipped in the scheduled view. This behavior can be understood by considering the control flow model described above, + +```python +: Quantum Circuit, first-measure +0 ░░░░░░░░░░░░▒▒▒▒▒▒░ +1 ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ + +: In wire q0 +Q ░░░░░░░░░░░░░░░▒▒▒░ +C ░░░░░░░░░░░░▒▒░░░░░ + +: In wire q1 +Q ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ +B ░░▒▒▒▒▒▒▒▒░░░░░░░░░ +D ░░░░░░░░░░▒▒▒▒▒▒░░░ +C ░░░░░░░░░░░░░░░░▒▒░ +``` + +Since there is no qubit register overlap between Q0 and Q1, the node ordering is determined by the shared classical register C. As you can see, the execution order is still preserved on C, i.e. read C then apply `XGate`, finally store the measured outcome in C. But because `DAGOpNode` cannot define different durations for the associated registers, the time ordering of the two nodes is inverted. + +This behavior can be controlled by `clbit_write_latency` and `conditional_latency`. `clbit_write_latency` determines the delay of the register write-access from the beginning of the measure instruction (t0), while `conditional_latency` determines the delay of conditional gate operations with respect to t0, which is determined by the register read-access. This information is accessible in the backend configuration and should be copied to the pass manager property set before the pass is called. + +Due to default latencies, the alap-scheduled circuit of above example may become + +```python + ┌───┐ +q_0: ───┤ X ├────── + └─╥─┘ ┌─┐ +q_1: ─────╫─────┤M├ + ┌────╨────┐└╥┘ +c: 1/╡ c_0=0x1 ╞═╩═ + └─────────┘ 0 +``` + +If the backend microarchitecture supports smart scheduling of the control flow instructions, such as separately scheduling qubits and classical registers, the insertion of the delay yields an unnecessarily longer total execution time. + +```python +: Quantum Circuit, first-XGate +0 ░▒▒▒░░░░░░░░░░░░░░░ +1 ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ + +: In wire q0 +Q ░▒▒▒░░░░░░░░░░░░░░░ +C ░░░░░░░░░░░░░░░░░░░ (zero latency) + +: In wire q1 +Q ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ +C ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ (zero latency, scheduled after C0 read-access) +``` + +However, this result is much more intuitive in the topological ordering view. If a finite conditional latency value is provided, for example, 30 dt, the circuit is scheduled as follows: + +```python + ┌───────────────┐ ┌───┐ +q_0: ┤ Delay(30[dt]) ├───┤ X ├────── + ├───────────────┤ └─╥─┘ ┌─┐ +q_1: ┤ Delay(30[dt]) ├─────╫─────┤M├ + └───────────────┘┌────╨────┐└╥┘ +c: 1/═════════════════╡ c_0=0x1 ╞═╩═ + └─────────┘ 0 +``` + +with the timing model: + +```python +: Quantum Circuit, first-xgate +0 ░░▒▒▒░░░░░░░░░░░░░░░ +1 ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ + +: In wire q0 +Q ░░▒▒▒░░░░░░░░░░░░░░░ +C ░▒░░░░░░░░░░░░░░░░░░ (30dt latency) + +: In wire q1 +Q ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ +C ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ +``` + +See [https://arxiv.org/abs/2102.01682](https://arxiv.org/abs/2102.01682) for more details. + +## Transpiler API + +### Transpiler Target + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target")(\[description, num\_qubits, dt, ...]) | The intent of the `Target` object is to inform Qiskit's compiler about the constraints of a particular backend so the compiler can compile an input circuit to something that works and is optimized for a device. | +| [`InstructionProperties`](qiskit.transpiler.InstructionProperties "qiskit.transpiler.InstructionProperties")(\[duration, error, ...]) | A representation of the properties of a gate implementation. | + +### Pass Manager Construction + +| | | +| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager")(\[stages]) | A pass manager pipeline built from individual stages. | +| [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager")(\[passes, max\_iteration]) | Manager for a set of Passes and their scheduling during transpilation. | +| [`PassManagerConfig`](qiskit.transpiler.PassManagerConfig "qiskit.transpiler.PassManagerConfig")(\[initial\_layout, ...]) | Pass Manager Configuration. | + +### Layout and Topology + +| | | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | +| [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout")(\[input\_dict]) | Two-ways dict to represent a Layout. | +| [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")(\[couplinglist, description]) | Directed graph specifying fixed coupling. | +| [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout")(initial\_layout, ...\[, ...]) | Layout attributes from output circuit from transpiler. | + +### Scheduling + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| [`InstructionDurations`](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations")(\[instruction\_durations, dt]) | Helper class to provide durations of instructions for scheduling. | + +### Fenced Objects + +| | | +| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| [`FencedPropertySet`](qiskit.transpiler.FencedPropertySet "qiskit.transpiler.FencedPropertySet")(property\_set\_instance) | A property set that cannot be written (via \_\_setitem\_\_) | +| [`FencedDAGCircuit`](qiskit.transpiler.FencedDAGCircuit "qiskit.transpiler.FencedDAGCircuit")(dag\_circuit\_instance) | A dag circuit that cannot be modified (via remove\_op\_node) | + +### Abstract Passes + +| | | +| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.TransformationPass")(\*args, \*\*kwargs) | A transformation pass: change DAG, not property set. | +| [`AnalysisPass`](qiskit.transpiler.AnalysisPass "qiskit.transpiler.AnalysisPass")(\*args, \*\*kwargs) | An analysis pass: change property set, not DAG. | + +### Exceptions + +### TranspilerError + + + +`qiskit.transpiler.TranspilerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/exceptions.py "view source code") + +Exceptions raised during transpilation. + +Set the error message. + +### TranspilerAccessError + + + +`qiskit.transpiler.TranspilerAccessError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/exceptions.py "view source code") + +DEPRECATED: Exception of access error in the transpiler passes. + +Set the error message. + +### CouplingError + + + +`qiskit.transpiler.CouplingError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/exceptions.py "view source code") + +Base class for errors raised by the coupling graph object. + +Set the error message. + +### LayoutError + + + +`qiskit.transpiler.LayoutError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/exceptions.py "view source code") + +Errors raised by the layout object. + +Set the error message. + diff --git a/docs/api/qiskit/0.46/transpiler_builtin_plugins.md b/docs/api/qiskit/0.46/transpiler_builtin_plugins.md new file mode 100644 index 00000000000..c5595272581 --- /dev/null +++ b/docs/api/qiskit/0.46/transpiler_builtin_plugins.md @@ -0,0 +1,8 @@ + + +# Built-in Transpiler Synthesis Plugins + +* [Approximate Quantum Compiler (`qiskit.synthesis.unitary.aqc`)](synthesis_aqc) + + * [Interface](synthesis_aqc#interface) + * [Mathematical Detail](synthesis_aqc#mathematical-detail) diff --git a/docs/api/qiskit/0.46/transpiler_passes.md b/docs/api/qiskit/0.46/transpiler_passes.md new file mode 100644 index 00000000000..186692598c3 --- /dev/null +++ b/docs/api/qiskit/0.46/transpiler_passes.md @@ -0,0 +1,162 @@ +--- +title: passes +description: API reference for qiskit.transpiler.passes +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.transpiler.passes +--- + + + + + + + +# Transpiler Passes + + + +`qiskit.transpiler.passes` + +## Layout Selection (Placement) + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| [`SetLayout`](qiskit.transpiler.passes.SetLayout "qiskit.transpiler.passes.SetLayout")(\*args, \*\*kwargs) | Set the `layout` property to the given layout. | +| [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout")(\*args, \*\*kwargs) | Choose a Layout by assigning `n` circuit qubits to device qubits `0, .., n-1`. | +| [`DenseLayout`](qiskit.transpiler.passes.DenseLayout "qiskit.transpiler.passes.DenseLayout")(\*args, \*\*kwargs) | Choose a Layout by finding the most connected subset of qubits. | +| [`NoiseAdaptiveLayout`](qiskit.transpiler.passes.NoiseAdaptiveLayout "qiskit.transpiler.passes.NoiseAdaptiveLayout")(\*args, \*\*kwargs) | Choose a noise-adaptive Layout based on current calibration data for the backend. | +| [`SabreLayout`](qiskit.transpiler.passes.SabreLayout "qiskit.transpiler.passes.SabreLayout")(\*args, \*\*kwargs) | Choose a Layout via iterative bidirectional routing of the input circuit. | +| [`CSPLayout`](qiskit.transpiler.passes.CSPLayout "qiskit.transpiler.passes.CSPLayout")(\*args, \*\*kwargs) | If possible, chooses a Layout as a CSP, using backtracking. | +| [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout")(\*args, \*\*kwargs) | A pass for choosing a Layout of a circuit onto a Coupling graph, as a subgraph isomorphism problem, solved by VF2++. | +| [`ApplyLayout`](qiskit.transpiler.passes.ApplyLayout "qiskit.transpiler.passes.ApplyLayout")(\*args, \*\*kwargs) | Transform a circuit with virtual qubits into a circuit with physical qubits. | +| [`Layout2qDistance`](qiskit.transpiler.passes.Layout2qDistance "qiskit.transpiler.passes.Layout2qDistance")(\*args, \*\*kwargs) | Evaluate how good the layout selection was. | +| [`EnlargeWithAncilla`](qiskit.transpiler.passes.EnlargeWithAncilla "qiskit.transpiler.passes.EnlargeWithAncilla")(\*args, \*\*kwargs) | Extend the dag with virtual qubits that are in layout but not in the circuit yet. | +| [`FullAncillaAllocation`](qiskit.transpiler.passes.FullAncillaAllocation "qiskit.transpiler.passes.FullAncillaAllocation")(\*args, \*\*kwargs) | Allocate all idle nodes from the coupling map or target as ancilla on the layout. | +| [`SabrePreLayout`](qiskit.transpiler.passes.SabrePreLayout "qiskit.transpiler.passes.SabrePreLayout")(\*args, \*\*kwargs) | Choose a starting layout to use for additional Sabre layout trials. | + +## Routing + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| [`BasicSwap`](qiskit.transpiler.passes.BasicSwap "qiskit.transpiler.passes.BasicSwap")(\*args, \*\*kwargs) | Map (with minimum effort) a DAGCircuit onto a `coupling_map` adding swap gates. | +| [`LookaheadSwap`](qiskit.transpiler.passes.LookaheadSwap "qiskit.transpiler.passes.LookaheadSwap")(\*args, \*\*kwargs) | Map input circuit onto a backend topology via insertion of SWAPs. | +| [`StochasticSwap`](qiskit.transpiler.passes.StochasticSwap "qiskit.transpiler.passes.StochasticSwap")(\*args, \*\*kwargs) | Map a DAGCircuit onto a coupling\_map adding swap gates. | +| [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap")(\*args, \*\*kwargs) | Map input circuit onto a backend topology via insertion of SWAPs. | +| [`Commuting2qGateRouter`](qiskit.transpiler.passes.Commuting2qGateRouter "qiskit.transpiler.passes.Commuting2qGateRouter")(\*args, \*\*kwargs) | A class to swap route one or more commuting gates to the coupling map. | + +## Basis Change + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| [`BasisTranslator`](qiskit.transpiler.passes.BasisTranslator "qiskit.transpiler.passes.BasisTranslator")(\*args, \*\*kwargs) | Translates gates to a target basis by searching for a set of translations from a given EquivalenceLibrary. | +| [`Decompose`](qiskit.transpiler.passes.Decompose "qiskit.transpiler.passes.Decompose")(\*args, \*\*kwargs) | Expand a gate in a circuit using its decomposition rules. | +| [`TranslateParameterizedGates`](qiskit.transpiler.passes.TranslateParameterizedGates "qiskit.transpiler.passes.TranslateParameterizedGates")(\*args, \*\*kwargs) | Translate parameterized gates to a supported basis set. | +| [`Unroll3qOrMore`](qiskit.transpiler.passes.Unroll3qOrMore "qiskit.transpiler.passes.Unroll3qOrMore")(\*args, \*\*kwargs) | Recursively expands 3q+ gates until the circuit only contains 2q or 1q gates. | +| [`UnrollCustomDefinitions`](qiskit.transpiler.passes.UnrollCustomDefinitions "qiskit.transpiler.passes.UnrollCustomDefinitions")(\*args, \*\*kwargs) | Unrolls instructions with custom definitions. | +| [`Unroller`](qiskit.transpiler.passes.Unroller "qiskit.transpiler.passes.Unroller")(\*args, \*\*kwargs) | Unroll a circuit to a given basis. | + +## Optimizations + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Optimize1qGates`](qiskit.transpiler.passes.Optimize1qGates "qiskit.transpiler.passes.Optimize1qGates")(\*args, \*\*kwargs) | Optimize chains of single-qubit u1, u2, u3 gates by combining them into a single gate. | +| [`Optimize1qGatesDecomposition`](qiskit.transpiler.passes.Optimize1qGatesDecomposition "qiskit.transpiler.passes.Optimize1qGatesDecomposition")(\*args, \*\*kwargs) | Optimize chains of single-qubit gates by combining them into a single gate. | +| [`Collect1qRuns`](qiskit.transpiler.passes.Collect1qRuns "qiskit.transpiler.passes.Collect1qRuns")(\*args, \*\*kwargs) | Collect one-qubit subcircuits. | +| [`Collect2qBlocks`](qiskit.transpiler.passes.Collect2qBlocks "qiskit.transpiler.passes.Collect2qBlocks")(\*args, \*\*kwargs) | Collect two-qubit subcircuits. | +| [`CollectMultiQBlocks`](qiskit.transpiler.passes.CollectMultiQBlocks "qiskit.transpiler.passes.CollectMultiQBlocks")(\*args, \*\*kwargs) | Collect sequences of uninterrupted gates acting on groups of qubits. | +| [`CollectLinearFunctions`](qiskit.transpiler.passes.CollectLinearFunctions "qiskit.transpiler.passes.CollectLinearFunctions")(\*args, \*\*kwargs) | Collect blocks of linear gates ([`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") and [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate") gates) and replaces them by linear functions ([`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction")). | +| [`CollectCliffords`](qiskit.transpiler.passes.CollectCliffords "qiskit.transpiler.passes.CollectCliffords")(\*args, \*\*kwargs) | Collects blocks of Clifford gates and replaces them by a [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") object. | +| [`ConsolidateBlocks`](qiskit.transpiler.passes.ConsolidateBlocks "qiskit.transpiler.passes.ConsolidateBlocks")(\*args, \*\*kwargs) | Replace each block of consecutive gates by a single Unitary node. | +| [`CXCancellation`](qiskit.transpiler.passes.CXCancellation "qiskit.transpiler.passes.CXCancellation")(\*args, \*\*kwargs) | Cancel back-to-back `cx` gates in dag. | +| [`InverseCancellation`](qiskit.transpiler.passes.InverseCancellation "qiskit.transpiler.passes.InverseCancellation")(\*args, \*\*kwargs) | Cancel specific Gates which are inverses of each other when they occur back-to- back. | +| [`CommutationAnalysis`](qiskit.transpiler.passes.CommutationAnalysis "qiskit.transpiler.passes.CommutationAnalysis")(\*args, \*\*kwargs) | Analysis pass to find commutation relations between DAG nodes. | +| [`CommutativeCancellation`](qiskit.transpiler.passes.CommutativeCancellation "qiskit.transpiler.passes.CommutativeCancellation")(\*args, \*\*kwargs) | Cancel the redundant (self-adjoint) gates through commutation relations. | +| [`CommutativeInverseCancellation`](qiskit.transpiler.passes.CommutativeInverseCancellation "qiskit.transpiler.passes.CommutativeInverseCancellation")(\*args, \*\*kwargs) | Cancel pairs of inverse gates exploiting commutation relations. | +| [`Optimize1qGatesSimpleCommutation`](qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation "qiskit.transpiler.passes.Optimize1qGatesSimpleCommutation")(\*args, \*\*kwargs) | Optimizes 1Q gate strings interrupted by 2Q gates by commuting the components and resynthesizing the results. | +| [`RemoveDiagonalGatesBeforeMeasure`](qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure "qiskit.transpiler.passes.RemoveDiagonalGatesBeforeMeasure")(\*args, \*\*kwargs) | Remove diagonal gates (including diagonal 2Q gates) before a measurement. | +| [`RemoveResetInZeroState`](qiskit.transpiler.passes.RemoveResetInZeroState "qiskit.transpiler.passes.RemoveResetInZeroState")(\*args, \*\*kwargs) | Remove reset gate when the qubit is in zero state. | +| [`CrosstalkAdaptiveSchedule`](qiskit.transpiler.passes.CrosstalkAdaptiveSchedule "qiskit.transpiler.passes.CrosstalkAdaptiveSchedule")(\*args, \*\*kwargs) | Crosstalk mitigation through adaptive instruction scheduling. | +| [`HoareOptimizer`](qiskit.transpiler.passes.HoareOptimizer "qiskit.transpiler.passes.HoareOptimizer")(\*args, \*\*kwargs) | This is a transpiler pass using Hoare logic circuit optimization. | +| [`TemplateOptimization`](qiskit.transpiler.passes.TemplateOptimization "qiskit.transpiler.passes.TemplateOptimization")(\*args, \*\*kwargs) | Class for the template optimization pass. | +| [`EchoRZXWeylDecomposition`](qiskit.transpiler.passes.EchoRZXWeylDecomposition "qiskit.transpiler.passes.EchoRZXWeylDecomposition")(\*args, \*\*kwargs) | Rewrite two-qubit gates using the Weyl decomposition. | +| [`ResetAfterMeasureSimplification`](qiskit.transpiler.passes.ResetAfterMeasureSimplification "qiskit.transpiler.passes.ResetAfterMeasureSimplification")(\*args, \*\*kwargs) | This pass replaces reset after measure with a conditional X gate. | +| [`OptimizeCliffords`](qiskit.transpiler.passes.OptimizeCliffords "qiskit.transpiler.passes.OptimizeCliffords")(\*args, \*\*kwargs) | Combine consecutive Cliffords over the same qubits. | +| [`NormalizeRXAngle`](qiskit.transpiler.passes.NormalizeRXAngle "qiskit.transpiler.passes.NormalizeRXAngle")(\*args, \*\*kwargs) | Normalize theta parameter of RXGate instruction. | + +## Calibration + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| [`PulseGates`](qiskit.transpiler.passes.PulseGates "qiskit.transpiler.passes.PulseGates")(\*args, \*\*kwargs) | Pulse gate adding pass. | +| [`RZXCalibrationBuilder`](qiskit.transpiler.passes.RZXCalibrationBuilder "qiskit.transpiler.passes.RZXCalibrationBuilder")(\*args, \*\*kwargs) | Creates calibrations for RZXGate(theta) by stretching and compressing Gaussian square pulses in the CX gate. | +| [`RZXCalibrationBuilderNoEcho`](qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho "qiskit.transpiler.passes.RZXCalibrationBuilderNoEcho")(\*args, \*\*kwargs) | Creates calibrations for RZXGate(theta) by stretching and compressing Gaussian square pulses in the CX gate. | +| [`RXCalibrationBuilder`](qiskit.transpiler.passes.RXCalibrationBuilder "qiskit.transpiler.passes.RXCalibrationBuilder")(\*args, \*\*kwargs) | Add single-pulse RX calibrations that are bootstrapped from the SX calibration. | + +## Scheduling + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| [`TimeUnitConversion`](qiskit.transpiler.passes.TimeUnitConversion "qiskit.transpiler.passes.TimeUnitConversion")(\*args, \*\*kwargs) | Choose a time unit to be used in the following time-aware passes, and make all circuit time units consistent with that. | +| [`ALAPScheduleAnalysis`](qiskit.transpiler.passes.ALAPScheduleAnalysis "qiskit.transpiler.passes.ALAPScheduleAnalysis")(\*args, \*\*kwargs) | ALAP Scheduling pass, which schedules the **stop** time of instructions as late as possible. | +| [`ASAPScheduleAnalysis`](qiskit.transpiler.passes.ASAPScheduleAnalysis "qiskit.transpiler.passes.ASAPScheduleAnalysis")(\*args, \*\*kwargs) | ASAP Scheduling pass, which schedules the start time of instructions as early as possible. | +| [`PadDynamicalDecoupling`](qiskit.transpiler.passes.PadDynamicalDecoupling "qiskit.transpiler.passes.PadDynamicalDecoupling")(\*args, \*\*kwargs) | Dynamical decoupling insertion pass. | +| [`PadDelay`](qiskit.transpiler.passes.PadDelay "qiskit.transpiler.passes.PadDelay")(\*args, \*\*kwargs) | Padding idle time with Delay instructions. | +| [`ConstrainedReschedule`](qiskit.transpiler.passes.ConstrainedReschedule "qiskit.transpiler.passes.ConstrainedReschedule")(\*args, \*\*kwargs) | Rescheduler pass that updates node start times to conform to the hardware alignments. | +| [`ValidatePulseGates`](qiskit.transpiler.passes.ValidatePulseGates "qiskit.transpiler.passes.ValidatePulseGates")(\*args, \*\*kwargs) | Check custom gate length. | +| [`InstructionDurationCheck`](qiskit.transpiler.passes.InstructionDurationCheck "qiskit.transpiler.passes.InstructionDurationCheck")(\*args, \*\*kwargs) | Duration validation pass for reschedule. | +| [`SetIOLatency`](qiskit.transpiler.passes.SetIOLatency "qiskit.transpiler.passes.SetIOLatency")(\*args, \*\*kwargs) | Set IOLatency information to the input circuit. | +| [`ALAPSchedule`](qiskit.transpiler.passes.ALAPSchedule "qiskit.transpiler.passes.ALAPSchedule")(\*args, \*\*kwargs) | ALAP Scheduling pass, which schedules the **stop** time of instructions as late as possible. | +| [`ASAPSchedule`](qiskit.transpiler.passes.ASAPSchedule "qiskit.transpiler.passes.ASAPSchedule")(\*args, \*\*kwargs) | ASAP Scheduling pass, which schedules the start time of instructions as early as possible.. | +| [`DynamicalDecoupling`](qiskit.transpiler.passes.DynamicalDecoupling "qiskit.transpiler.passes.DynamicalDecoupling")(\*args, \*\*kwargs) | Dynamical decoupling insertion pass. | +| [`AlignMeasures`](qiskit.transpiler.passes.AlignMeasures "qiskit.transpiler.passes.AlignMeasures")(\*args, \*\*kwargs) | Measurement alignment. | + +## Circuit Analysis + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Width`](qiskit.transpiler.passes.Width "qiskit.transpiler.passes.Width")(\*args, \*\*kwargs) | Calculate the width of a DAG circuit. | +| [`Depth`](qiskit.transpiler.passes.Depth "qiskit.transpiler.passes.Depth")(\*args, \*\*kwargs) | Calculate the depth of a DAG circuit. | +| [`Size`](qiskit.transpiler.passes.Size "qiskit.transpiler.passes.Size")(\*args, \*\*kwargs) | Calculate the size of a DAG circuit. | +| [`CountOps`](qiskit.transpiler.passes.CountOps "qiskit.transpiler.passes.CountOps")(\*args, \*\*kwargs) | Count the operations in a DAG circuit. | +| [`CountOpsLongestPath`](qiskit.transpiler.passes.CountOpsLongestPath "qiskit.transpiler.passes.CountOpsLongestPath")(\*args, \*\*kwargs) | Count the operations on the longest path in a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit"). | +| [`NumTensorFactors`](qiskit.transpiler.passes.NumTensorFactors "qiskit.transpiler.passes.NumTensorFactors")(\*args, \*\*kwargs) | Calculate the number of tensor factors of a DAG circuit. | +| [`DAGLongestPath`](qiskit.transpiler.passes.DAGLongestPath "qiskit.transpiler.passes.DAGLongestPath")(\*args, \*\*kwargs) | Return the longest path in a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") as a list of [`DAGOpNode`](qiskit.dagcircuit.DAGOpNode "qiskit.dagcircuit.DAGOpNode")s, [`DAGInNode`](qiskit.dagcircuit.DAGInNode "qiskit.dagcircuit.DAGInNode")s, and [`DAGOutNode`](qiskit.dagcircuit.DAGOutNode "qiskit.dagcircuit.DAGOutNode")s. | + +## Synthesis + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| [`UnitarySynthesis`](qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis")(\*args, \*\*kwargs) | Synthesize gates according to their basis gates. | +| [`LinearFunctionsSynthesis`](qiskit.transpiler.passes.LinearFunctionsSynthesis "qiskit.transpiler.passes.LinearFunctionsSynthesis")(\*args, \*\*kwargs) | DEPRECATED: Synthesize linear functions. | +| [`LinearFunctionsToPermutations`](qiskit.transpiler.passes.LinearFunctionsToPermutations "qiskit.transpiler.passes.LinearFunctionsToPermutations")(\*args, \*\*kwargs) | Promotes linear functions to permutations when possible. | +| [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis")(\*args, \*\*kwargs) | Synthesize higher-level objects and unroll custom definitions. | +| [`SolovayKitaev`](qiskit.transpiler.passes.SolovayKitaev "qiskit.transpiler.passes.SolovayKitaev")(\*args, \*\*kwargs) | Approximately decompose 1q gates to a discrete basis using the Solovay-Kitaev algorithm. | +| [`SolovayKitaevSynthesis`](qiskit.transpiler.passes.SolovayKitaevSynthesis "qiskit.transpiler.passes.SolovayKitaevSynthesis")() | A Solovay-Kitaev Qiskit unitary synthesis plugin. | +| [`AQCSynthesisPlugin`](qiskit.transpiler.passes.AQCSynthesisPlugin "qiskit.transpiler.passes.AQCSynthesisPlugin")() | An AQC-based Qiskit unitary synthesis plugin. | + +## Post Layout (Post transpile qubit selection) + +| | | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| [`VF2PostLayout`](qiskit.transpiler.passes.VF2PostLayout "qiskit.transpiler.passes.VF2PostLayout")(\*args, \*\*kwargs) | A pass for choosing a Layout after transpilation of a circuit onto a Coupling graph, as a subgraph isomorphism problem, solved by VF2++. | + +## Additional Passes + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| [`CheckMap`](qiskit.transpiler.passes.CheckMap "qiskit.transpiler.passes.CheckMap")(\*args, \*\*kwargs) | Check if a DAG circuit is already mapped to a coupling map. | +| [`CheckGateDirection`](qiskit.transpiler.passes.CheckGateDirection "qiskit.transpiler.passes.CheckGateDirection")(\*args, \*\*kwargs) | Check if the two-qubit gates follow the right direction with respect to the coupling map. | +| [`GateDirection`](qiskit.transpiler.passes.GateDirection "qiskit.transpiler.passes.GateDirection")(\*args, \*\*kwargs) | Modify asymmetric gates to match the hardware coupling direction. | +| [`MergeAdjacentBarriers`](qiskit.transpiler.passes.MergeAdjacentBarriers "qiskit.transpiler.passes.MergeAdjacentBarriers")(\*args, \*\*kwargs) | Return a circuit with any adjacent barriers merged together. | +| [`RemoveBarriers`](qiskit.transpiler.passes.RemoveBarriers "qiskit.transpiler.passes.RemoveBarriers")(\*args, \*\*kwargs) | Return a circuit with any barrier removed. | +| [`BarrierBeforeFinalMeasurements`](qiskit.transpiler.passes.BarrierBeforeFinalMeasurements "qiskit.transpiler.passes.BarrierBeforeFinalMeasurements")(\*args, \*\*kwargs) | Add a barrier before final measurements. | +| [`RemoveFinalMeasurements`](qiskit.transpiler.passes.RemoveFinalMeasurements "qiskit.transpiler.passes.RemoveFinalMeasurements")(\*args, \*\*kwargs) | Remove final measurements and barriers at the end of a circuit. | +| [`DAGFixedPoint`](qiskit.transpiler.passes.DAGFixedPoint "qiskit.transpiler.passes.DAGFixedPoint")(\*args, \*\*kwargs) | Check if the DAG has reached a fixed point. | +| [`FixedPoint`](qiskit.transpiler.passes.FixedPoint "qiskit.transpiler.passes.FixedPoint")(\*args, \*\*kwargs) | Check if a property reached a fixed point. | +| [`MinimumPoint`](qiskit.transpiler.passes.MinimumPoint "qiskit.transpiler.passes.MinimumPoint")(\*args, \*\*kwargs) | Check if the DAG has reached a relative semi-stable point over previous runs | +| [`ContainsInstruction`](qiskit.transpiler.passes.ContainsInstruction "qiskit.transpiler.passes.ContainsInstruction")(\*args, \*\*kwargs) | An analysis pass to detect if the DAG contains a specific instruction. | +| [`GatesInBasis`](qiskit.transpiler.passes.GatesInBasis "qiskit.transpiler.passes.GatesInBasis")(\*args, \*\*kwargs) | Check if all gates in a DAG are in a given set of gates | +| [`ConvertConditionsToIfOps`](qiskit.transpiler.passes.ConvertConditionsToIfOps "qiskit.transpiler.passes.ConvertConditionsToIfOps")(\*args, \*\*kwargs) | Convert instructions whose `condition` attribute is set to a non-`None` value into the equivalent single-statement `IfElseBlock`. | +| [`UnrollForLoops`](qiskit.transpiler.passes.UnrollForLoops "qiskit.transpiler.passes.UnrollForLoops")(\*args, \*\*kwargs) | `UnrollForLoops` transpilation pass unrolls for-loops when possible. | + diff --git a/docs/api/qiskit/0.46/transpiler_plugins.md b/docs/api/qiskit/0.46/transpiler_plugins.md new file mode 100644 index 00000000000..8a999a278ca --- /dev/null +++ b/docs/api/qiskit/0.46/transpiler_plugins.md @@ -0,0 +1,170 @@ +--- +title: plugin +description: API reference for qiskit.transpiler.preset_passmanagers.plugin +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.transpiler.preset_passmanagers.plugin +--- + + + + + + + +# Transpiler Stage Plugin Interface + + + +`qiskit.transpiler.preset_passmanagers.plugin` + +This module defines the plugin interface for providing custom stage implementations for the preset pass managers and the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function. This enables external Python packages to provide [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") objects that can be used for each named stage. + +The plugin interfaces are built using setuptools [entry points](https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html) which enable packages external to Qiskit to advertise they include a transpiler stage(s). + +For details on how to instead write plugins for transpiler synthesis methods, see [`qiskit.transpiler.passes.synthesis.plugin`](transpiler_synthesis_plugins#module-qiskit.transpiler.passes.synthesis.plugin "qiskit.transpiler.passes.synthesis.plugin"). + + + +## Plugin Stages + +Currently, there are 6 stages in the preset pass managers, all of which actively load external plugins via corresponding entry points. + +| Stage Name | Entry Point | Reserved Names | Description and expectations | +| -------------- | -------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `init` | `qiskit.transpiler.init` | `default` | This stage runs first and is typically used for any initial logical optimization. Because most layout and routing algorithms are only designed to work with 1 and 2 qubit gates, this stage is also used to translate any gates that operate on more than 2 qubits into gates that only operate on 1 or 2 qubits. | +| `layout` | `qiskit.transpiler.layout` | `trivial`, `dense`, `noise_adaptive`, `sabre`, `default` | The output from this stage is expected to have the `layout` property set field set with a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object. Additionally, the circuit is typically expected to be embedded so that it is expanded to include all qubits and the [`ApplyLayout`](qiskit.transpiler.passes.ApplyLayout "qiskit.transpiler.passes.ApplyLayout") pass is expected to be run to apply the layout. The embedding of the [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") can be generated with [`generate_embed_passmanager()`](transpiler_preset#qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager "qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager"). | +| `routing` | `qiskit.transpiler.routing` | `basic`, `stochastic`, `lookahead`, `sabre`, `toqm` | The output from this stage is expected to have the circuit match the connectivity constraints of the target backend. This does not necessarily need to match the directionality of the edges in the target as a later stage typically will adjust directional gates to match that constraint (but there is no penalty for doing that in the `routing` stage). | +| `translation` | `qiskit.transpiler.translation` | `translator`, `synthesis`, `unroller` | **The output of this stage is expected to have every operation be a native**instruction on the target backend. | +| `optimization` | `qiskit.transpiler.optimization` | `default` | This stage is expected to perform optimization and simplification. The constraints from earlier stages still apply to the output of this stage. After the `optimization` stage is run we expect the circuit to still be executable on the target. | +| `scheduling` | `qiskit.transpiler.scheduling` | `alap`, `asap`, `default` | This is the last stage run and it is expected to output a scheduled circuit such that all idle periods in the circuit are marked by explicit [`Delay`](qiskit.circuit.Delay "qiskit.circuit.Delay") instructions. | + +## Writing Plugins + +To write a pass manager stage plugin there are 2 main steps. The first step is to create a subclass of the abstract plugin class [`PassManagerStagePlugin`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin") which is used to define how the [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") for the stage will be constructed. For example, to create a `layout` stage plugin that just runs [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout") (with increasing amount of trials, depending on the optimization level) and falls back to using [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout") if `VF2Layout` is unable to find a perfect layout: + +```python +from qiskit.transpiler.preset_passmanagers.plugin import PassManagerStagePlugin +from qiskit.transpiler.preset_passmanagers import common +from qiskit.transpiler import PassManager +from qiskit.transpiler.passes import VF2Layout, TrivialLayout +from qiskit.transpiler.passes.layout.vf2_layout import VF2LayoutStopReason + + +def _vf2_match_not_found(property_set): + return property_set["layout"] is None or ( + property_set["VF2Layout_stop_reason"] is not None + and property_set["VF2Layout_stop_reason"] is not VF2LayoutStopReason.SOLUTION_FOUND + + +class VF2LayoutPlugin(PassManagerStagePlugin): + + def pass_manager(self, pass_manager_config, optimization_level): + layout_pm = PassManager( + [ + VF2Layout( + coupling_map=pass_manager_config.coupling_map, + properties=pass_manager_config.backend_properties, + max_trials=optimization_level * 10 + 1 + target=pass_manager_config.target + ) + ] + ) + layout_pm.append( + TrivialLayout(pass_manager_config.coupling_map), + condition=_vf2_match_not_found, + ) + layout_pm += common.generate_embed_passmanager(pass_manager_config.coupling_map) + return layout_pm +``` + +The second step is to expose the [`PassManagerStagePlugin`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin") subclass as a setuptools entry point in the package metadata. This can be done by simply adding an `entry_points` entry to the `setuptools.setup` call in the `setup.py` or the plugin package with the necessary entry points under the appropriate namespace for the stage your plugin is for. You can see the list of stages, entry points, and expectations from the stage in [Plugin Stages](#stage-table). For example, continuing from the example plugin above: + +```python +entry_points = { + 'qiskit.transpiler.layout': [ + 'vf2 = qiskit_plugin_pkg.module.plugin:VF2LayoutPlugin', + ] +}, +``` + +Note that the entry point `name = path` is a single string not a Python expression. There isn’t a limit to the number of plugins a single package can include as long as each plugin has a unique name. So a single package can expose multiple plugins if necessary. Refer to [Plugin Stages](#stage-table) for a list of reserved names for each stage. + +## Plugin API + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`PassManagerStagePlugin`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin")() | A `PassManagerStagePlugin` is a plugin interface object for using custom stages in [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"). | +| [`PassManagerStagePluginManager`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager")() | Manager class for preset pass manager stage plugins. | + +### list\_stage\_plugins + + + +`qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins(stage_name)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") + +Get a list of installed plugins for a stage. + +**Parameters** + +**stage\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The stage name to get the plugin names for + +**Returns** + +The list of installed plugin names for the specified stages + +**Return type** + +plugins + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If an invalid stage name is specified. + +### passmanager\_stage\_plugins + + + +`qiskit.transpiler.preset_passmanagers.plugin.passmanager_stage_plugins(stage)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/plugin.py "view source code") + +Return a dict with, for each stage name, the class type of the plugin. + +This function is useful for getting more information about a plugin: + +```python +from qiskit.transpiler.preset_passmanagers.plugin import passmanager_stage_plugins +routing_plugins = passmanager_stage_plugins('routing') +basic_plugin = routing_plugins['basic'] +help(basic_plugin) +``` + +```python +Help on BasicSwapPassManager in module ...preset_passmanagers.builtin_plugins object: + +class BasicSwapPassManager(...preset_passmanagers.plugin.PassManagerStagePlugin) + | Plugin class for routing stage with :class:`~.BasicSwap` + | + | Method resolution order: + | BasicSwapPassManager + | ...preset_passmanagers.plugin.PassManagerStagePlugin + | abc.ABC + | builtins.object + ... +``` + +**Parameters** + +**stage** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The stage name to get + +**Returns** + +the key is the name of the plugin and the value is the class type for each. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If an invalid stage name is specified. + diff --git a/docs/api/qiskit/0.46/transpiler_preset.md b/docs/api/qiskit/0.46/transpiler_preset.md new file mode 100644 index 00000000000..06e2c6b6741 --- /dev/null +++ b/docs/api/qiskit/0.46/transpiler_preset.md @@ -0,0 +1,398 @@ +--- +title: preset_passmanagers +description: API reference for qiskit.transpiler.preset_passmanagers +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.transpiler.preset_passmanagers +--- + + + + + + + +# Preset Passmanagers + + + +`qiskit.transpiler.preset_passmanagers` + +This module contains functions for generating the preset pass managers for the transpiler. The preset pass managers are instances of [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager") which are used to execute the circuit transformations as part of Qiskit’s compiler inside the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function at the different optimization levels. The functionality here is divided into two parts, the first includes the functions used generate the entire pass manager which is used by [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") ([Preset Pass Manager Generation](#preset-pass-manager-generators)) and the second includes functions which are used to build (either entirely or in part) the stages which the preset pass managers are composed of ([Stage Generator Functions](#stage-generators)). + + + +## Preset Pass Manager Generation + +### generate\_preset\_pass\_manager + + + +`qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager(optimization_level, backend=None, target=None, basis_gates=None, inst_map=None, coupling_map=None, instruction_durations=None, backend_properties=None, timing_constraints=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, approximation_degree=None, seed_transpiler=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None, init_method=None, optimization_method=None, *, _skip_target=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/__init__.py "view source code") + +Generate a preset [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +This function is used to quickly generate a preset pass manager. A preset pass manager are the default pass managers used by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function. This function provides a convenient and simple method to construct a standalone [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") object that mirrors what the transpile + +**Parameters** + +* **optimization\_level** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – + + The optimization level to generate a [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") for. This can be 0, 1, 2, or 3. Higher levels generate more optimized circuits, at the expense of longer transpilation time: + + > * 0: no optimization + > * 1: light optimization + > * 2: heavy optimization + > * 3: even heavier optimization + +* **backend** ([*Backend*](qiskit.providers.Backend "qiskit.providers.Backend")) – An optional backend object which can be used as the source of the default values for the `basis_gates`, `inst_map`, `couplig_map`, `backend_properties`, `instruction_durations`, `timing_constraints`, and `target`. If any of those other arguments are specified in addition to `backend` they will take precedence over the value contained in the backend. + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") representing a backend compilation target. The following attributes will be inferred from this argument if they are not set: `coupling_map`, `basis_gates`, `instruction_durations`, `inst_map`, `timing_constraints` and `backend_properties`. + +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – List of basis gate names to unroll to (e.g: `['u1', 'u2', 'u3', 'cx']`). + +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")) – Mapping object that maps gate to schedules. If any user defined calibration is found in the map and this is used in a circuit, transpiler attaches the custom gate definition to the circuit. This enables one to flexibly override the low-level instruction implementation. + +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – Directed graph represented a coupling map. + +* **instruction\_durations** ([*InstructionDurations*](qiskit.transpiler.InstructionDurations "qiskit.transpiler.InstructionDurations")) – Dictionary of duration (in dt) for each instruction. + +* **timing\_constraints** (*TimingConstraints*) – Hardware time alignment restrictions. + +* **initial\_layout** ([*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – Initial position of virtual qubits on physical qubits. + +* **layout\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The `Pass` to use for choosing initial qubit placement. Valid choices are `'trivial'`, `'dense'`, `'noise_adaptive'`, and, `'sabre'` representing [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout"), `DenseLayout`, [`NoiseAdaptiveLayout`](qiskit.transpiler.passes.NoiseAdaptiveLayout "qiskit.transpiler.passes.NoiseAdaptiveLayout"), [`SabreLayout`](qiskit.transpiler.passes.SabreLayout "qiskit.transpiler.passes.SabreLayout") respectively. This can also be the external plugin name to use for the `layout` stage of the output [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"layout"` for the `stage_name` argument. + +* **routing\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The pass to use for routing qubits on the architecture. Valid choices are `'basic'`, `'lookahead'`, `'stochastic'`, `'sabre'`, and `'none'` representing [`BasicSwap`](qiskit.transpiler.passes.BasicSwap "qiskit.transpiler.passes.BasicSwap"), [`LookaheadSwap`](qiskit.transpiler.passes.LookaheadSwap "qiskit.transpiler.passes.LookaheadSwap"), [`StochasticSwap`](qiskit.transpiler.passes.StochasticSwap "qiskit.transpiler.passes.StochasticSwap"), [`SabreSwap`](qiskit.transpiler.passes.SabreSwap "qiskit.transpiler.passes.SabreSwap"), and erroring if routing is required respectively. This can also be the external plugin name to use for the `routing` stage of the output [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"routing"` for the `stage_name` argument. + +* **translation\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The method to use for translating gates to basis gates. Valid choices `'unroller'`, `'translator'`, `'synthesis'` representing [`Unroller`](qiskit.transpiler.passes.Unroller "qiskit.transpiler.passes.Unroller"), [`BasisTranslator`](qiskit.transpiler.passes.BasisTranslator "qiskit.transpiler.passes.BasisTranslator"), and [`UnitarySynthesis`](qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") respectively. This can also be the external plugin name to use for the `translation` stage of the output [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"translation"` for the `stage_name` argument. + +* **scheduling\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The pass to use for scheduling instructions. Valid choices are `'alap'` and `'asap'`. This can also be the external plugin name to use for the `scheduling` stage of the output [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"scheduling"` for the `stage_name` argument. + +* **backend\_properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – Properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. + +* **approximation\_degree** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – Heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation). + +* **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets random seed for the stochastic parts of the transpiler. + +* **unitary\_synthesis\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the unitary synthesis method to use. By default `'default'` is used. You can see a list of installed plugins with [`unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names"). + +* **unitary\_synthesis\_plugin\_config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – An optional configuration dictionary that will be passed directly to the unitary synthesis plugin. By default this setting will have no effect as the default unitary synthesis method does not take custom configuration. This should only be necessary when a unitary synthesis plugin is specified with the `unitary_synthesis` argument. As this is custom for each unitary synthesis plugin refer to the plugin documentation for how to use this option. + +* **hls\_config** (*HLSConfig*) – An optional configuration class `HLSConfig` that will be passed directly to [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis") transformation pass. This configuration class allows to specify for various high-level objects the lists of synthesis algorithms and their parameters. + +* **init\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The plugin name to use for the `init` stage of the output [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). By default an external plugin is not used. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"init"` for the stage name argument. + +* **optimization\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The plugin name to use for the `optimization` stage of the output [`StagedPassManager`](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager"). By default an external plugin is not used. You can see a list of installed plugins by using [`list_stage_plugins()`](transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"optimization"` for the `stage_name` argument. + +**Returns** + +The preset pass manager for the given options + +**Return type** + +[StagedPassManager](qiskit.transpiler.StagedPassManager "qiskit.transpiler.StagedPassManager") + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if an invalid value for `optimization_level` is passed in. + +### level\_0\_pass\_manager + + + +`qiskit.transpiler.preset_passmanagers.level_0_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/level0.py "view source code") + +Level 0 pass manager: no explicit optimization other than mapping to backend. + +This pass manager applies the user-given initial layout. If none is given, a trivial layout consisting of mapping the i-th virtual qubit to the i-th physical qubit is used. Any unused physical qubit is allocated as ancilla space. + +The pass manager then unrolls the circuit to the desired basis, and transforms the circuit to match the coupling map. + +**Parameters** + +**pass\_manager\_config** ([*PassManagerConfig*](qiskit.transpiler.PassManagerConfig "qiskit.transpiler.passmanager_config.PassManagerConfig")) – configuration of the pass manager. + +**Returns** + +a level 0 pass manager. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the passmanager config is invalid. + +**Return type** + +[*StagedPassManager*](qiskit.transpiler.StagedPassManager "qiskit.transpiler.passmanager.StagedPassManager") + +### level\_1\_pass\_manager + + + +`qiskit.transpiler.preset_passmanagers.level_1_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/level1.py "view source code") + +Level 1 pass manager: light optimization by simple adjacent gate collapsing. + +This pass manager applies the user-given initial layout. If none is given, and a trivial layout (i-th virtual -> i-th physical) makes the circuit fit the coupling map, that is used. Otherwise, the circuit is mapped to the most densely connected coupling subgraph, and swaps are inserted to map. Any unused physical qubit is allocated as ancilla space. The pass manager then unrolls the circuit to the desired basis, and transforms the circuit to match the coupling map. Finally, optimizations in the form of adjacent gate collapse and redundant reset removal are performed. + +**Parameters** + +**pass\_manager\_config** ([*PassManagerConfig*](qiskit.transpiler.PassManagerConfig "qiskit.transpiler.passmanager_config.PassManagerConfig")) – configuration of the pass manager. + +**Returns** + +a level 1 pass manager. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the passmanager config is invalid. + +**Return type** + +[*StagedPassManager*](qiskit.transpiler.StagedPassManager "qiskit.transpiler.passmanager.StagedPassManager") + +### level\_2\_pass\_manager + + + +`qiskit.transpiler.preset_passmanagers.level_2_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/level2.py "view source code") + +Level 2 pass manager: medium optimization by initial layout selection and gate cancellation using commutativity rules. + +This pass manager applies the user-given initial layout. If none is given, a search for a perfect layout (i.e. one that satisfies all 2-qubit interactions) is conducted. If no such layout is found, qubits are laid out on the most densely connected subset which also exhibits the best gate fidelities. + +The pass manager then transforms the circuit to match the coupling constraints. It is then unrolled to the basis, and any flipped cx directions are fixed. Finally, optimizations in the form of commutative gate cancellation and redundant reset removal are performed. + +**Parameters** + +**pass\_manager\_config** ([*PassManagerConfig*](qiskit.transpiler.PassManagerConfig "qiskit.transpiler.passmanager_config.PassManagerConfig")) – configuration of the pass manager. + +**Returns** + +a level 2 pass manager. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the passmanager config is invalid. + +**Return type** + +[*StagedPassManager*](qiskit.transpiler.StagedPassManager "qiskit.transpiler.passmanager.StagedPassManager") + +### level\_3\_pass\_manager + + + +`qiskit.transpiler.preset_passmanagers.level_3_pass_manager(pass_manager_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/level3.py "view source code") + +Level 3 pass manager: heavy optimization by noise adaptive qubit mapping and gate cancellation using commutativity rules and unitary synthesis. + +This pass manager applies the user-given initial layout. If none is given, a search for a perfect layout (i.e. one that satisfies all 2-qubit interactions) is conducted. If no such layout is found, and device calibration information is available, the circuit is mapped to the qubits with best readouts and to CX gates with highest fidelity. + +The pass manager then transforms the circuit to match the coupling constraints. It is then unrolled to the basis, and any flipped cx directions are fixed. Finally, optimizations in the form of commutative gate cancellation, resynthesis of two-qubit unitary blocks, and redundant reset removal are performed. + +**Parameters** + +**pass\_manager\_config** ([*PassManagerConfig*](qiskit.transpiler.PassManagerConfig "qiskit.transpiler.passmanager_config.PassManagerConfig")) – configuration of the pass manager. + +**Returns** + +a level 3 pass manager. + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – if the passmanager config is invalid. + +**Return type** + +[*StagedPassManager*](qiskit.transpiler.StagedPassManager "qiskit.transpiler.passmanager.StagedPassManager") + + + +## Stage Generator Functions + +### generate\_control\_flow\_options\_check + + + +`qiskit.transpiler.preset_passmanagers.common.generate_control_flow_options_check(layout_method=None, routing_method=None, translation_method=None, optimization_method=None, scheduling_method=None, basis_gates=(), target=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate a pass manager that, when run on a DAG that contains control flow, fails with an error message explaining the invalid options, and what could be used instead. + +**Returns** + +a pass manager that populates the `contains_x` properties for each of the control-flow operations, and raises an error if any of the given options do not support control flow, but a circuit with control flow is given. + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +### generate\_error\_on\_control\_flow + + + +`qiskit.transpiler.preset_passmanagers.common.generate_error_on_control_flow(message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Get a pass manager that always raises an error if control flow is present in a given circuit. + +### generate\_unroll\_3q + + + +`qiskit.transpiler.preset_passmanagers.common.generate_unroll_3q(target, basis_gates=None, approximation_degree=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate an unroll >3q [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the backend +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of str gate names that represent the basis gates on the backend target +* **approximation\_degree** (*Optional\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The heuristic approximation degree to use. Can be between 0 and 1. +* **unitary\_synthesis\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unitary synthesis method to use. You can see a list of installed plugins with [`unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names"). +* **unitary\_synthesis\_plugin\_config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The optional dictionary plugin configuration, this is plugin specific refer to the specified plugin’s documentation for how to use. +* **hls\_config** (*HLSConfig*) – An optional configuration class to use for [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis") pass. Specifies how to synthesize various high-level objects. + +**Returns** + +The unroll 3q or more pass manager + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +### generate\_embed\_passmanager + + + +`qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager(coupling_map)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate a layout embedding [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +This is used to generate a [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") object that can be used to expand and apply an initial layout to a circuit + +**Parameters** + +**coupling\_map** (*Union\[*[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")*,* [*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The coupling map for the backend to embed the circuit to. + +**Returns** + +**The embedding passmanager that assumes the layout property** + +set has been set in earlier stages + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +### generate\_routing\_passmanager + + + +`qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager(routing_pass, target, coupling_map=None, vf2_call_limit=None, backend_properties=None, seed_transpiler=None, check_trivial=False, use_barrier_before_measurement=True, vf2_max_trials=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate a routing [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +**Parameters** + +* **routing\_pass** ([*TransformationPass*](qiskit.transpiler.TransformationPass "qiskit.transpiler.TransformationPass")) – The pass which will perform the routing +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the backend +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – The coupling map of the backend to route for +* **vf2\_call\_limit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The internal call limit for the vf2 post layout pass. If this is `None` or `0` the vf2 post layout will not be run. +* **backend\_properties** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – Properties of a backend to synthesize for (e.g. gate fidelities). +* **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Sets random seed for the stochastic parts of the transpiler. +* **check\_trivial** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If set to true this will condition running the [`VF2PostLayout`](qiskit.transpiler.passes.VF2PostLayout "qiskit.transpiler.passes.VF2PostLayout") pass after routing on whether a trivial layout was tried and was found to not be perfect. This is only needed if the constructed pass manager runs [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout") as a first layout attempt and uses it if it’s a perfect layout (as is the case with preset pass manager level 1). +* **use\_barrier\_before\_measurement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If true (the default) the [`BarrierBeforeFinalMeasurements`](qiskit.transpiler.passes.BarrierBeforeFinalMeasurements "qiskit.transpiler.passes.BarrierBeforeFinalMeasurements") transpiler pass will be run prior to the specified pass in the `routing_pass` argument. +* **vf2\_max\_trials** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The maximum number of trials to run VF2 when evaluating the vf2 post layout pass. If this is `None` or `0` the vf2 post layout will not be run. + +**Returns** + +The routing pass manager + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +### generate\_pre\_op\_passmanager + + + +`qiskit.transpiler.preset_passmanagers.common.generate_pre_op_passmanager(target=None, coupling_map=None, remove_reset_in_zero=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate a pre-optimization loop [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +This pass manager will check to ensure that directionality from the coupling map is respected + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the backend +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – The coupling map to use +* **remove\_reset\_in\_zero** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If `True` include the remove reset in zero pass in the generated PassManager + +**Returns** + +The pass manager + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +### generate\_translation\_passmanager + + + +`qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager(target, basis_gates=None, method='translator', approximation_degree=None, coupling_map=None, backend_props=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate a basis translation [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +**Parameters** + +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the backend +* **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – A list of str gate names that represent the basis gates on the backend target +* **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The basis translation method to use +* **approximation\_degree** (*Optional\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")*]*) – The heuristic approximation degree to use. Can be between 0 and 1. +* **coupling\_map** ([*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")) – the coupling map of the backend in case synthesis is done on a physical circuit. The directionality of the coupling\_map will be taken into account if pulse\_optimize is True/None and natural\_direction is True/None. +* **unitary\_synthesis\_plugin\_config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The optional dictionary plugin configuration, this is plugin specific refer to the specified plugin’s documentation for how to use. +* **backend\_props** ([*BackendProperties*](qiskit.providers.models.BackendProperties "qiskit.providers.models.BackendProperties")) – Properties of a backend to synthesize for (e.g. gate fidelities). +* **unitary\_synthesis\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unitary synthesis method to use. You can see a list of installed plugins with [`unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names"). +* **hls\_config** (*HLSConfig*) – An optional configuration class to use for [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.HighLevelSynthesis") pass. Specifies how to synthesize various high-level objects. + +**Returns** + +The basis translation pass manager + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the `method` kwarg is not a valid value + +### generate\_scheduling + + + +`qiskit.transpiler.preset_passmanagers.common.generate_scheduling(instruction_durations, scheduling_method, timing_constraints, inst_map, target=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/transpiler/preset_passmanagers/common.py "view source code") + +Generate a post optimization scheduling [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +**Parameters** + +* **instruction\_durations** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – The dictionary of instruction durations +* **scheduling\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The scheduling method to use, can either be `'asap'`/`'as_soon_as_possible'` or `'alap'`/`'as_late_as_possible'` +* **timing\_constraints** (*TimingConstraints*) – Hardware time alignment restrictions. +* **inst\_map** ([*InstructionScheduleMap*](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")) – Mapping object that maps gate to schedule. +* **target** ([*Target*](qiskit.transpiler.Target "qiskit.transpiler.Target")) – The [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target") object representing the backend + +**Returns** + +The scheduling pass manager + +**Return type** + +[PassManager](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") + +**Raises** + +[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If the `scheduling_method` kwarg is not a valid value + diff --git a/docs/api/qiskit/0.46/transpiler_synthesis_plugins.md b/docs/api/qiskit/0.46/transpiler_synthesis_plugins.md new file mode 100644 index 00000000000..cb32aa6c3a6 --- /dev/null +++ b/docs/api/qiskit/0.46/transpiler_synthesis_plugins.md @@ -0,0 +1,169 @@ +--- +title: plugin +description: API reference for qiskit.transpiler.passes.synthesis.plugin +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.transpiler.passes.synthesis.plugin +--- + + + + + + + +# Synthesis Plugins + + + +`qiskit.transpiler.passes.synthesis.plugin` + +This module defines the plugin interfaces for the synthesis transpiler passes in Qiskit. These provide a hook point for external python packages to implement their own synthesis techniques and have them seamlessly exposed as opt-in options to users when they run [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"). + +The plugin interfaces are built using setuptools [entry points](https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html) which enable packages external to qiskit to advertise they include a synthesis plugin. + +See [`qiskit.transpiler.preset_passmanagers.plugin`](transpiler_plugins#module-qiskit.transpiler.preset_passmanagers.plugin "qiskit.transpiler.preset_passmanagers.plugin") for details on how to write plugins for transpiler stages. + +## Writing Plugins + +### Unitary Synthesis Plugins + +To write a unitary synthesis plugin there are 2 main steps. The first step is to create a subclass of the abstract plugin class: [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin"). The plugin class defines the interface and contract for unitary synthesis plugins. The primary method is [`run()`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin#run "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.run") which takes in a single positional argument, a unitary matrix as a numpy array, and is expected to return a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") object representing the synthesized circuit from that unitary matrix. Then to inform the Qiskit transpiler about what information is necessary for the pass there are several required property methods that need to be implemented such as `supports_basis_gates` and `supports_coupling_map` depending on whether the plugin supports and/or requires that input to perform synthesis. For the full details refer to the [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") documentation for all the required fields. An example plugin class would look something like: + +```python +from qiskit.transpiler.passes.synthesis import plugin +from qiskit_plugin_pkg.synthesis import generate_dag_circuit_from_matrix + + +class SpecialUnitarySynthesis(plugin.UnitarySynthesisPlugin): + @property + def supports_basis_gates(self): + return True + + @property + def supports_coupling_map(self): + return False + + @property + def supports_natural_direction(self): + return False + + @property + def supports_pulse_optimize(self): + return False + + @property + def supports_gate_lengths(self): + return False + + @property + def supports_gate_errors(self): + return False + + @property + def supports_gate_lengths_by_qubit(self): + return False + + @property + def supports_gate_errors_by_qubit(self): + return False + + @property + def min_qubits(self): + return None + + @property + def max_qubits(self): + return None + + @property + def supported_bases(self): + return None + + def run(self, unitary, **options): + basis_gates = options['basis_gates'] + dag_circuit = generate_dag_circuit_from_matrix(unitary, basis_gates) + return dag_circuit +``` + +If for some reason the available inputs to the [`run()`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin#run "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin.run") method are insufficient please open an issue and we can discuss expanding the plugin interface with new opt-in inputs that can be added in a backwards compatible manner for future releases. Do note though that this plugin interface is considered stable and guaranteed to not change in a breaking manner. If changes are needed (for example to expand the available optional input options) it will be done in a way that will **not** require changes from existing plugins. + + + All methods prefixed with `supports_` are reserved on a `UnitarySynthesisPlugin` derived class for part of the interface. You should not define any custom `supports_*` methods on a subclass that are not defined in the abstract class. + + +The second step is to expose the [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin") as a setuptools entry point in the package metadata. This is done by simply adding an `entry_points` entry to the `setuptools.setup` call in the `setup.py` for the plugin package with the necessary entry points under the `qiskit.unitary_synthesis` namespace. For example: + +```python +entry_points = { + 'qiskit.unitary_synthesis': [ + 'special = qiskit_plugin_pkg.module.plugin:SpecialUnitarySynthesis', + ] +}, +``` + +(note that the entry point `name = path` is a single string not a Python expression). There isn’t a limit to the number of plugins a single package can include as long as each plugin has a unique name. So a single package can expose multiple plugins if necessary. The name `default` is used by Qiskit itself and can’t be used in a plugin. + +#### Unitary Synthesis Plugin Configuration + +For some unitary synthesis plugins that expose multiple options and tunables the plugin interface has an option for users to provide a free form configuration dictionary. This will be passed through to the `run()` method as the `config` kwarg. If your plugin has these configuration options you should clearly document how a user should specify these configuration options and how they’re used as it’s a free form field. + +### High-Level Synthesis Plugins + +Writing a high-level synthesis plugin is conceptually similar to writing a unitary synthesis plugin. The first step is to create a subclass of the abstract plugin class: [`HighLevelSynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin"), which defines the interface and contract for high-level synthesis plugins. The primary method is [`run()`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin#run "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.run"). The positional argument `high_level_object` specifies the “higher-level-object” to be synthesized, which is any object of type [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") (including, for example, [`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.generalized_gates.linear_function.LinearFunction") or [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.operators.symplectic.clifford.Clifford")). The keyword argument `target` specifies the target backend, allowing the plugin to access all target-specific information, such as the coupling map, the supported gate set, and so on. The keyword argument `coupling_map` only specifies the coupling map, and is only used when `target` is not specified. The keyword argument `qubits` specifies the list of qubits over which the higher-level-object is defined, in case the synthesis is done on the physical circuit. The value of `None` indicates that the layout has not yet been chosen and the physical qubits in the target or coupling map that this operation is operating on has not yet been determined. Additionally, plugin-specific options and tunables can be specified via `options`, which is a free form configuration dictionary. If your plugin has these configuration options you should clearly document how a user should specify these configuration options and how they’re used as it’s a free form field. The method [`run()`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin#run "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin.run") is expected to return a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object representing the synthesized circuit from that higher-level-object. It is also allowed to return `None` representing that the synthesis method is unable to synthesize the given higher-level-object. The actual synthesis of higher-level objects is performed by [`HighLevelSynthesis`](qiskit.transpiler.passes.HighLevelSynthesis "qiskit.transpiler.passes.synthesis.high_level_synthesis.HighLevelSynthesis") transpiler pass. For the full details refer to the [`HighLevelSynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin") documentation for all the required fields. An example plugin class would look something like: + +```python +from qiskit.transpiler.passes.synthesis.plugin import HighLevelSynthesisPlugin +from qiskit.synthesis.clifford import synth_clifford_bm + + +class SpecialSynthesisClifford(HighLevelSynthesisPlugin): + +def run(self, high_level_object, coupling_map=None, target=None, qubits=None, **options): + if higher_level_object.num_qubits <= 3: + return synth_clifford_bm(high_level_object) + else: + return None +``` + +The above example creates a plugin to synthesize objects of type [`Clifford`](qiskit.quantum_info.Clifford "qiskit.quantum_info.Clifford") that have at most 3 qubits, using the method `synth_clifford_bm`. + +The second step is to expose the [`HighLevelSynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin") as a setuptools entry point in the package metadata. This is done by adding an `entry_points` entry to the `setuptools.setup` call in the `setup.py` for the plugin package with the necessary entry points under the `qiskit.synthesis` namespace. For example: + +```python +entry_points = { + 'qiskit.synthesis': [ + 'clifford.special = qiskit_plugin_pkg.module.plugin:SpecialSynthesisClifford', + ] +}, +``` + +(note that the entry point `name = path` is a single string not a Python expression). The `name` consists of two parts separated by dot “.”: the name of the type of [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") to which the synthesis plugin applies (`clifford`), and the name of the plugin (`special`). There isn’t a limit to the number of plugins a single package can include as long as each plugin has a unique name. + +## Using Plugins + +To use a plugin all you need to do is install the package that includes a synthesis plugin. Then Qiskit will automatically discover the installed plugins and expose them as valid options for the appropriate [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") kwargs and pass constructors. If there are any installed plugins which can’t be loaded/imported this will be logged to Python logging. + +To get the installed list of installed unitary synthesis plugins you can use the [`qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names()`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names") function. + +## Plugin API + + + +### Unitary Synthesis Plugins + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| [`UnitarySynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin")() | Abstract unitary synthesis plugin class | +| [`UnitarySynthesisPluginManager`](qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager "qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPluginManager")() | Unitary Synthesis plugin manager class | +| [`unitary_synthesis_plugin_names`](qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names")() | Return a list of installed unitary synthesis plugin names | + + + +### High-Level Synthesis Plugins + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| [`HighLevelSynthesisPlugin`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPlugin")() | Abstract high-level synthesis plugin class. | +| [`HighLevelSynthesisPluginManager`](qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager "qiskit.transpiler.passes.synthesis.plugin.HighLevelSynthesisPluginManager")() | Class tracking the installed high-level-synthesis plugins. | + diff --git a/docs/api/qiskit/0.46/utils.md b/docs/api/qiskit/0.46/utils.md new file mode 100644 index 00000000000..b7b8bc4ec70 --- /dev/null +++ b/docs/api/qiskit/0.46/utils.md @@ -0,0 +1,712 @@ +--- +title: utils +description: API reference for qiskit.utils +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.utils +--- + + + + + + + +# Utilities + + + +`qiskit.utils` + +### add\_deprecation\_to\_docstring + + + +`qiskit.utils.add_deprecation_to_docstring(func, msg, *, since, pending)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/deprecation.py "view source code") + +Dynamically insert the deprecation message into `func`’s docstring. + +**Parameters** + +* **func** (*Callable*) – The function to modify. +* **msg** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The full deprecation message. +* **since** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The version the deprecation started at. +* **pending** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Is the deprecation still pending? + +### deprecate\_arg + + + +`qiskit.utils.deprecate_arg(name, *, since, additional_msg=None, deprecation_description=None, pending=False, package_name='qiskit', new_alias=None, predicate=None, removal_timeline='no earlier than 3 months after the release date')`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/deprecation.py "view source code") + +Decorator to indicate an argument has been deprecated in some way. + +This decorator may be used multiple times on the same function, once per deprecated argument. It should be placed beneath other decorators like `@staticmethod` and property decorators. + +**Parameters** + +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The name of the deprecated argument. +* **since** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The version the deprecation started at. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update since to the new version. +* **deprecation\_description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – What is being deprecated? E.g. “Setting my\_func()’s my\_arg argument to None.” If not set, will default to “\{func\_name}’s argument \{name}”. +* **additional\_msg** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Put here any additional information, such as what to use instead (if new\_alias is not set). For example, “Instead, use the argument new\_arg, which is similar but does not impact the circuit’s setup.” +* **pending** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to True if the deprecation is still pending. +* **package\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The PyPI package name, e.g. “qiskit-nature”. +* **new\_alias** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – If the arg has simply been renamed, set this to the new name. The decorator will dynamically update the kwargs so that when the user sets the old arg, it will be passed in as the new\_alias arg. +* **predicate** (*Callable\[\[Any],* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")*] | None*) – Only log the runtime warning if the predicate returns True. This is useful to deprecate certain values or types for an argument, e.g. lambda my\_arg: isinstance(my\_arg, dict). Regardless of if a predicate is set, the runtime warning will only log when the user specifies the argument. +* **removal\_timeline** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – How soon can this deprecation be removed? Expects a value like “no sooner than 6 months after the latest release” or “in release 9.99”. + +**Returns** + +The decorated callable. + +**Return type** + +Callable + +### deprecate\_arguments + + + +`qiskit.utils.deprecate_arguments(kwarg_map, category=, *, since=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/deprecation.py "view source code") + +Deprecated. Instead, use @deprecate\_arg. + +**Parameters** + +* **kwarg\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None]*) – A dictionary of the old argument name to the new name. +* **category** ([*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")*\[*[*Warning*](https://docs.python.org/3/library/exceptions.html#Warning "(in Python v3.12)")*]*) – Usually either DeprecationWarning or PendingDeprecationWarning. +* **since** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The version the deprecation started at. Only Optional for backwards compatibility - this should always be set. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update since to the new version. + +**Returns** + +The decorated callable. + +**Return type** + +Callable + +### deprecate\_func + + + +`qiskit.utils.deprecate_func(*, since, additional_msg=None, pending=False, package_name='qiskit', removal_timeline='no earlier than 3 months after the release date', is_property=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/deprecation.py "view source code") + +Decorator to indicate a function has been deprecated. + +It should be placed beneath other decorators like @staticmethod and property decorators. + +When deprecating a class, set this decorator on its \_\_init\_\_ function. + +**Parameters** + +* **since** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The version the deprecation started at. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update `since` to the new version. +* **additional\_msg** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Put here any additional information, such as what to use instead. For example, “Instead, use the function `new_func` from the module `.`, which is similar but uses GPU acceleration.” +* **pending** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set to `True` if the deprecation is still pending. +* **package\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The PyPI package name, e.g. “qiskit-nature”. +* **removal\_timeline** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – How soon can this deprecation be removed? Expects a value like “no sooner than 6 months after the latest release” or “in release 9.99”. +* **is\_property** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If the deprecated function is a @property, set this to True so that the generated message correctly describes it as such. (This isn’t necessary for property setters, as their docstring is ignored by Python.) + +**Returns** + +The decorated callable. + +**Return type** + +Callable + +### deprecate\_function + + + +`qiskit.utils.deprecate_function(msg, stacklevel=2, category=, *, since=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/deprecation.py "view source code") + +Deprecated. Instead, use @deprecate\_func. + +**Parameters** + +* **msg** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Warning message to emit. +* **stacklevel** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – The warning stacklevel to use, defaults to 2. +* **category** ([*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")*\[*[*Warning*](https://docs.python.org/3/library/exceptions.html#Warning "(in Python v3.12)")*]*) – Usually either DeprecationWarning or PendingDeprecationWarning. +* **since** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – The version the deprecation started at. Only Optional for backwards compatibility - this should always be set. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update since to the new version. + +**Returns** + +The decorated, deprecated callable. + +**Return type** + +Callable + +### local\_hardware\_info + + + +`qiskit.utils.local_hardware_info()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/multiprocessing.py "view source code") + +Basic hardware information about the local machine. + +Gives actual number of CPU’s in the machine, even when hyperthreading is turned on. CPU count defaults to 1 when true count can’t be determined. + +**Returns** + +The hardware information. + +**Return type** + +[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") + +### is\_main\_process + + + +`qiskit.utils.is_main_process()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/multiprocessing.py "view source code") + +Checks whether the current process is the main one + +### apply\_prefix + + + +`qiskit.utils.apply_prefix(value, unit)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/units.py "view source code") + +Given a SI unit prefix and value, apply the prefix to convert to standard SI unit. + +**Parameters** + +* **value** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") *|*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")) – The number to apply prefix to. +* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – String prefix. + +**Returns** + +Converted value. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [ParameterExpression](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") + + + This may induce tiny value error due to internal representation of float object. See [https://docs.python.org/3/tutorial/floatingpoint.html](https://docs.python.org/3/tutorial/floatingpoint.html) for details. + + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the `units` aren’t recognized. + +**Return type** + +[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)") | [ParameterExpression](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression") + +### detach\_prefix + + + +`qiskit.utils.detach_prefix(value, decimal=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/units.py "view source code") + +Given a SI unit value, find the most suitable prefix to scale the value. + +For example, the `value = 1.3e8` will be converted into a tuple of `(130.0, "M")`, which represents a scaled value and auxiliary unit that may be used to display the value. In above example, that value might be displayed as `130 MHz` (unit is arbitrary here). + +**Example** + +```python +>>> value, prefix = detach_prefix(1e4) +>>> print(f"{value} {prefix}Hz") +10 kHz +``` + +**Parameters** + +* **value** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")) – The number to find prefix. +* **decimal** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)") *| None*) – Optional. An arbitrary integer number to represent a precision of the value. If specified, it tries to round the mantissa and adjust the prefix to rounded value. For example, 999\_999.91 will become 999.9999 k with `decimal=4`, while 1.0 M with `decimal=3` or less. + +**Returns** + +A tuple of scaled value and prefix. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + + + This may induce tiny value error due to internal representation of float object. See [https://docs.python.org/3/tutorial/floatingpoint.html](https://docs.python.org/3/tutorial/floatingpoint.html) for details. + + +**Raises** + +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the `value` is out of range. +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – If the `value` is not real number. + +**Return type** + +[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)"), [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")] + +### wrap\_method + + + +`qiskit.utils.wrap_method(cls, name, *, before=None, after=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/classtools.py "view source code") + +Wrap the functionality the instance- or class method `cls.name` with additional behaviour `before` and `after`. + +This mutates `cls`, replacing the attribute `name` with the new functionality. This is useful when creating class decorators. The method is allowed to be defined on any parent class instead. + +If either `before` or `after` are given, they should be callables with a compatible signature to the method referred to. They will be called immediately before or after the method as appropriate, and any return value will be ignored. + +**Parameters** + +* **cls** ([*Type*](https://docs.python.org/3/library/typing.html#typing.Type "(in Python v3.12)")) – the class to modify. +* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the name of the method on the class to wrap. +* **before** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – a callable that should be called before the method that is being wrapped. +* **after** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.12)") *| None*) – a callable that should be called after the method that is being wrapped. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if the named method is not defined on the class or any parent class. + +## Algorithm Utilities + +### summarize\_circuits + + + +`qiskit.utils.summarize_circuits(circuits)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/circuit_utils.py "view source code") + +**Summarize circuits based on QuantumCircuit, and five metrics are summarized.** + +* Number of qubits +* Number of classical bits +* Number of operations +* Depth of circuits +* Counts of different gate operations + +The average statistic of the first four is provided if multiple circuits are provided. + +> +> The function `qiskit.utils.circuit_utils.summarize_circuits()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was only used in the context of qiskit.opflow/qiskit.algorithms, two modules deprecated and planned to be removed in Qiskit 1.0. +> + +**Parameters** + +**circuits** ([*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") *or \[*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – the to-be-summarized circuits + +**Returns** + +a formatted string records the summary + +**Return type** + +[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") + +### get\_entangler\_map + + + +`qiskit.utils.get_entangler_map(map_type, num_qubits, offset=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/entangler_map.py "view source code") + +Utility method to get an entangler map among qubits. + + + The function `qiskit.utils.entangler_map.get_entangler_map()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was only used in the context of qiskit.opflow/qiskit.algorithms, two modules deprecated and planned to be removed in Qiskit 1.0. + + +**Parameters** + +* **map\_type** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – ‘full’ entangles each qubit with all the subsequent ones ‘linear’ entangles each qubit with the next ‘sca’ (shifted circular alternating entanglement) is a circular entanglement where the ‘long’ entanglement is shifted by one position every block and every block the role or control/target qubits alternate +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of qubits for which the map is needed +* **offset** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Some map\_types (e.g. ‘sca’) can shift the gates in the entangler map by the specified integer offset. + +**Returns** + +A map of qubit index to an array of indexes to which this should be entangled + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if map\_type is not valid. + +### validate\_entangler\_map + + + +`qiskit.utils.validate_entangler_map(entangler_map, num_qubits, allow_double_entanglement=False)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/entangler_map.py "view source code") + +Validate a user supplied entangler map and converts entries to ints. + + + The function `qiskit.utils.entangler_map.validate_entangler_map()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was only used in the context of qiskit.opflow/qiskit.algorithms, two modules deprecated and planned to be removed in Qiskit 1.0. + + +**Parameters** + +* **entangler\_map** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*]*) – An entangler map, keys are source qubit index (int), value is array of target qubit index(es) (int) +* **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of qubits +* **allow\_double\_entanglement** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – If we allow in two qubits can be entangled each other + +**Returns** + +Validated/converted map + +**Return type** + +[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)") + +**Raises** + +* [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – entangler map is not list type or list of list +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – the index of entangler map is out of range +* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – the qubits are cross-entangled. + +### has\_ibmq + + + +`qiskit.utils.has_ibmq()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/backend_utils.py "view source code") + +Check if IBMQ is installed. + + + The function `qiskit.utils.backend_utils.has_ibmq()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/qi\_migration](https://qisk.it/qi_migration). + + +### has\_aer + + + +`qiskit.utils.has_aer()`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/backend_utils.py "view source code") + +Check if Aer is installed. + + + The function `qiskit.utils.backend_utils.has_aer()` is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. For code migration guidelines, visit [https://qisk.it/qi\_migration](https://qisk.it/qi_migration). + + +### name\_args + + + +`qiskit.utils.name_args(mapping, skip=0)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/name_unnamed_args.py "view source code") + +Decorator to convert unnamed arguments to named ones. + +Can be used to deprecate old signatures of a function, e.g. + +```python +old_f(a: TypeA, b: TypeB, c: TypeC) +new_f(a: TypeA, d: TypeD, b: TypeB=None, c: TypeC=None) +``` + +Then, to support the old signature this decorator can be used as + +```python +@name_args([ + ('a'), # stays the same + ('d', {TypeB: 'b'}), # if arg is of type TypeB, call if 'b' else 'd' + ('b', {TypeC: 'c'}) +]) +def new_f(a: TypeA, d: TypeD, b: TypeB=None, c: TypeC=None): + if b is not None: + # raise warning, this is deprecated! + if c is not None: + # raise warning, this is deprecated! +``` + + + The function `qiskit.utils.name_unnamed_args.name_args()` is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was only used in the context of qiskit.opflow/qiskit.algorithms, two modules deprecated and planned to be removed in Qiskit 1.0. + + +**qiskit.utils.algorithm\_globals *= \*** + +Class for global properties. + +| | | +| -------------------------------------------------------------------------------- | -------------------------------------------------------- | +| [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") | Deprecated: Quantum Backend including execution setting. | + +A QuantumInstance holds the Qiskit backend as well as a number of compile and runtime parameters controlling circuit compilation and execution. Quantum [`algorithms`](algorithms#module-qiskit.algorithms "qiskit.algorithms") are run on a device or simulator by passing a QuantumInstance setup with the desired backend etc. + +### Parallel Routines + +A helper function for calling a custom function with python `ProcessPoolExecutor`. Tasks can be executed in parallel using this function. It has a built-in event publisher to show the progress of the parallel tasks. + +### parallel\_map + + + +`qiskit.utils.parallel_map(task, values, task_args=(), task_kwargs={}, num_processes=2)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/parallel.py "view source code") + +Parallel execution of a mapping of values to the function task. This is functionally equivalent to: + +```python +result = [task(value, *task_args, **task_kwargs) for value in values] +``` + +On Windows this function defaults to a serial implementation to avoid the overhead from spawning processes in Windows. + +**Parameters** + +* **task** (*func*) – Function that is to be called for each value in `values`. +* **values** (*array\_like*) – List or array of values for which the `task` function is to be evaluated. +* **task\_args** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")) – Optional additional arguments to the `task` function. +* **task\_kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")) – Optional additional keyword argument to the `task` function. +* **num\_processes** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Number of processes to spawn. + +**Returns** + +**The result list contains the value of** + +**`task(value, *task_args, **task_kwargs)` for** + +each value in `values`. + +**Return type** + +result + +**Raises** + +[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – If user interrupts via keyboard. + +**Events:** + +terra.parallel.start: The collection of parallel tasks are about to start. terra.parallel.update: One of the parallel task has finished. terra.parallel.finish: All the parallel tasks have finished. + +**Examples** + +```python +import time +from qiskit.tools.parallel import parallel_map +def func(_): + time.sleep(0.1) + return 0 +parallel_map(func, list(range(10))); +``` + + + + + +## Optional Dependency Checkers + + + +`qiskit.utils.optionals` + +Qiskit has several features that are enabled only if certain *optional* dependencies are satisfied. This module is a collection of objects that can be used to test if certain functionality is available, and optionally raise [`MissingOptionalLibraryError`](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") if the functionality is not available. + +### Available Testers + +#### Qiskit Components + +| | | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **qiskit.utils.optionals.HAS\_AER** | [Qiskit Aer](https://qiskit.org/ecosystem/aer/) provides high-performance simulators for the quantum circuits constructed within Qiskit. | +| **qiskit.utils.optionals.HAS\_IBMQ** | The Qiskit IBMQ Provider was historically used for accessing IBM Quantum hardware in the IBM cloud, but is now deprecated. | +| **qiskit.utils.optionals.HAS\_IGNIS** | Qiskit Ignis provided tools for quantum hardware verification, noise characterization, and error correction, but is now deprecated. | +| **qiskit.utils.optionals.HAS\_TOQM** | [Qiskit TOQM](https://github.com/qiskit-toqm/qiskit-toqm) provides transpiler passes for the [Time-optimal Qubit mapping algorithm](https://doi.org/10.1145/3445814.3446706). | + +#### External Python Libraries + +| | | +| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **qiskit.utils.optionals.HAS\_CONSTRAINT** | python-constraint \<[https://github.com/python-constraint/python-constraint>\_\_](https://github.com/python-constraint/python-constraint>__) is a constraint satisfaction problem solver, used in the :class:\`\~.CSPLayout transpiler pass. | +| **qiskit.utils.optionals.HAS\_CPLEX** | The [IBM CPLEX Optimizer](https://www.ibm.com/analytics/cplex-optimizer) is a high-performance mathematical programming solver for linear, mixed-integer and quadratic programming. This is no longer by Qiskit, but it weas historically and the optional remains for backwards compatibility. | +| **qiskit.utils.optionals.HAS\_CVXPY** | [CVXPY](https://www.cvxpy.org/) is a Python package for solving convex optimization problems. It is required for calculating diamond norms with [`quantum_info.diamond_norm()`](quantum_info#qiskit.quantum_info.diamond_norm "qiskit.quantum_info.diamond_norm"). | +| **qiskit.utils.optionals.HAS\_DOCPLEX** | [IBM Decision Optimization CPLEX Modelling](http://ibmdecisionoptimization.github.io/docplex-doc/) is a library for prescriptive analysis. Like CPLEX, this is no longer by Qiskit, but it weas historically and the optional remains for backwards compatibility. | +| **qiskit.utils.optionals.HAS\_FIXTURES** | The test suite has additional features that are available if the optional [fixtures](https://launchpad.net/python-fixtures) module is installed. This generally also needs [`HAS_TESTTOOLS`](#qiskit.utils.optionals.HAS_TESTTOOLS "qiskit.utils.optionals.HAS_TESTTOOLS") as well. This is generally only needed for Qiskit developers. | +| **qiskit.utils.optionals.HAS\_IPYTHON** | If [the IPython kernel](https://ipython.org/) is available, certain additional visualisations and line magics are made available. | +| **qiskit.utils.optionals.HAS\_IPYWIDGETS** | Monitoring widgets for jobs running on external backends can be provided if [ipywidgets](https://ipywidgets.readthedocs.io/en/latest/) is available. | +| **qiskit.utils.optionals.HAS\_JAX** | Some methods of gradient calculation within [`opflow.gradients`](qiskit.opflow.gradients#module-qiskit.opflow.gradients "qiskit.opflow.gradients") require [JAX](https://github.com/google/jax) for autodifferentiation. | +| **qiskit.utils.optionals.HAS\_JUPYTER** | Some of the tests require a complete [Jupyter](https://jupyter.org/) installation to test interactivity features. | +| **qiskit.utils.optionals.HAS\_MATPLOTLIB** | Qiskit provides several visualisation tools in the [`visualization`](visualization#module-qiskit.visualization "qiskit.visualization") module. Almost all of these are built using [Matplotlib](https://matplotlib.org/), which must be installed in order to use them. | +| **qiskit.utils.optionals.HAS\_NETWORKX** | No longer used by Qiskit. Internally, Qiskit now uses the high-performance [rustworkx](https://github.com/Qiskit/rustworkx) library as a core dependency, and during the change-over period, it was sometimes convenient to convert things into the Python-only [NetworkX](https://networkx.org/) format. Some tests of application modules, such as [Qiskit Nature](https://qiskit.org/ecosystem/nature/) still use NetworkX. | +| **qiskit.utils.optionals.HAS\_NLOPT** | [NLopt](https://nlopt.readthedocs.io/en/latest/) is a nonlinear optimization library, used by the global optimizers in the [`algorithms.optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers") module. | +| **qiskit.utils.optionals.HAS\_PIL** | PIL is a Python image-manipulation library. Qiskit actually uses the [pillow](https://pillow.readthedocs.io/en/stable/) fork of PIL if it is available when generating certain visualizations, for example of both [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") and [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") in certain modes. | +| **qiskit.utils.optionals.HAS\_PYDOT** | For some graph visualisations, Qiskit uses [pydot](https://github.com/pydot/pydot) as an interface to GraphViz (see [`HAS_GRAPHVIZ`](#qiskit.utils.optionals.HAS_GRAPHVIZ "qiskit.utils.optionals.HAS_GRAPHVIZ")). | +| **qiskit.utils.optionals.HAS\_PYGMENTS** | Pygments is a code highlighter and formatter used by many environments that involve rich display of code blocks, including Sphinx and Jupyter. Qiskit uses this when producing rich output for these environments. | +| **qiskit.utils.optionals.HAS\_PYLATEX** | Various LaTeX-based visualizations, especially the circuit drawers, need access to the [pylatexenc](https://github.com/phfaist/pylatexenc) project to work correctly. | +| **qiskit.utils.optionals.HAS\_QASM3\_IMPORT** | The functions [`qasm3.load()`](qasm3#qiskit.qasm3.load "qiskit.qasm3.load") and [`qasm3.loads()`](qasm3#qiskit.qasm3.loads "qiskit.qasm3.loads") for importing OpenQASM 3 programs into [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") instances use [an external importer package](https://qiskit.github.io/qiskit-qasm3-import). | +| **qiskit.utils.optionals.HAS\_SEABORN** | Qiskit provides several visualisation tools in the [`visualization`](visualization#module-qiskit.visualization "qiskit.visualization") module. Some of these are built using [Seaborn](https://seaborn.pydata.org/), which must be installed in order to use them. | +| **qiskit.utils.optionals.HAS\_SKLEARN** | Some of the gradient functions in [`opflow.gradients`](qiskit.opflow.gradients#module-qiskit.opflow.gradients "qiskit.opflow.gradients") use regularisation methods from [Scikit Learn](https://scikit-learn.org/stable/). | +| **qiskit.utils.optionals.HAS\_SKQUANT** | Some of the optimisers in [`algorithms.optimizers`](qiskit.algorithms.optimizers#module-qiskit.algorithms.optimizers "qiskit.algorithms.optimizers") are based on those found in [Scikit Quant](https://github.com/scikit-quant/scikit-quant), which must be installed to use them. | +| **qiskit.utils.optionals.HAS\_SQSNOBFIT** | [SQSnobFit](https://pypi.org/project/SQSnobFit/) is a library for the “stable noisy optimization by branch and fit” algorithm. It is used by the [`SNOBFIT`](qiskit.algorithms.optimizers.SNOBFIT "qiskit.algorithms.optimizers.SNOBFIT") optimizer. | +| **qiskit.utils.optionals.HAS\_SYMENGINE** | [Symengine](https://github.com/symengine/symengine) is a fast C++ backend for the symbolic-manipulation library [Sympy](https://www.sympy.org/en/index.html). Qiskit uses special methods from Symengine to accelerate its handling of [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")s if available. | +| **qiskit.utils.optionals.HAS\_TESTTOOLS** | Qiskit’s test suite has more advanced functionality available if the optional [testtools](https://pypi.org/project/testtools/) library is installed. This is generally only needed for Qiskit developers. | +| **qiskit.utils.optionals.HAS\_TWEEDLEDUM** | [Tweedledum](https://github.com/boschmitt/tweedledum) is an extension library for synthesis and optimization of circuits that may involve classical oracles. Qiskit’s [`PhaseOracle`](qiskit.circuit.library.PhaseOracle "qiskit.circuit.library.PhaseOracle") uses this, which is used in turn by amplification algorithms via the [`AmplificationProblem`](qiskit.algorithms.AmplificationProblem "qiskit.algorithms.AmplificationProblem"). | +| **qiskit.utils.optionals.HAS\_Z3** | [Z3](https://github.com/Z3Prover/z3) is a theorem prover, used in the [`CrosstalkAdaptiveSchedule`](qiskit.transpiler.passes.CrosstalkAdaptiveSchedule "qiskit.transpiler.passes.CrosstalkAdaptiveSchedule") and [`HoareOptimizer`](qiskit.transpiler.passes.HoareOptimizer "qiskit.transpiler.passes.HoareOptimizer") transpiler passes. | + +#### External Command-Line Tools + +| | | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **qiskit.utils.optionals.HAS\_GRAPHVIZ** | For some graph visualisations, Qiskit uses the [GraphViz](https://graphviz.org/) visualisation tool via its `pydot` interface (see [`HAS_PYDOT`](#qiskit.utils.optionals.HAS_PYDOT "qiskit.utils.optionals.HAS_PYDOT")). | +| **qiskit.utils.optionals.HAS\_PDFLATEX** | Visualisation tools that use LaTeX in their output, such as the circuit drawers, require `pdflatex` to be available. You will generally need to ensure that you have a working LaTeX installation available, and the `qcircuit.tex` package. | +| **qiskit.utils.optionals.HAS\_PDFTOCAIRO** | Visualisation tools that convert LaTeX-generated files into rasterised images use the `pdftocairo` tool. This is part of the [Poppler suite of PDF tools](https://poppler.freedesktop.org/). | + +### Lazy Checker Classes + +Each of the lazy checkers is an instance of [`LazyDependencyManager`](#qiskit.utils.LazyDependencyManager "qiskit.utils.LazyDependencyManager") in one of its two subclasses: [`LazyImportTester`](#qiskit.utils.LazyImportTester "qiskit.utils.LazyImportTester") and [`LazySubprocessTester`](#qiskit.utils.LazySubprocessTester "qiskit.utils.LazySubprocessTester"). These should be imported from [`utils`](#module-qiskit.utils "qiskit.utils") directly if required, such as: + +```python +from qiskit.utils import LazyImportTester +``` + + + +`qiskit.utils.LazyDependencyManager(*, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/lazy_tester.py "view source code") + +A mananger for some optional features that are expensive to import, or to verify the existence of. + +These objects can be used as Booleans, such as `if x`, and will evaluate `True` if the dependency they test for is available, and `False` if not. The presence of the dependency will only be tested when the Boolean is evaluated, so it can be used as a runtime test in functions and methods without requiring an import-time test. + +These objects also encapsulate the error handling if their dependency is not present, so you can do things such as: + +```python +from qiskit.utils import LazyImportManager +HAS_MATPLOTLIB = LazyImportManager("matplotlib") + +@HAS_MATPLOTLIB.require_in_call +def my_visualisation(): + ... + +def my_other_visualisation(): + # ... some setup ... + HAS_MATPLOTLIB.require_now("my_other_visualisation") + ... + +def my_third_visualisation(): + if HAS_MATPLOTLIB: + from matplotlib import pyplot + else: + ... +``` + +In all of these cases, `matplotlib` is not imported until the functions are entered. In the case of the decorator, `matplotlib` is tested for import when the function is called for the first time. In the second and third cases, the loader attempts to import `matplotlib` when the [`require_now()`](#qiskit.utils.LazyDependencyManager.require_now "qiskit.utils.LazyDependencyManager.require_now") method is called, or when the Boolean context is evaluated. For the `require` methods, an error is raised if the library is not available. + +This is the base class, which provides the Boolean context checking and error management. The concrete classes [`LazyImportTester`](#qiskit.utils.LazyImportTester "qiskit.utils.LazyImportTester") and [`LazySubprocessTester`](#qiskit.utils.LazySubprocessTester "qiskit.utils.LazySubprocessTester") provide convenient entry points for testing that certain symbols are importable from modules, or certain command-line tools are available, respectively. + +**Parameters** + +* **name** – the name of this optional dependency. +* **callback** – a callback that is called immediately after the availability of the library is tested with the result. This will only be called once. +* **install** – how to install this optional dependency. Passed to [`MissingOptionalLibraryError`](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") as the `pip_install` parameter. +* **msg** – an extra message to include in the error raised if this is required. + +### \_is\_available + + + +`abstract _is_available()` + +Subclasses of [`LazyDependencyManager`](#qiskit.utils.LazyDependencyManager "qiskit.utils.LazyDependencyManager") should override this method to implement the actual test of availability. This method should return a Boolean, where `True` indicates that the dependency was available. This method will only ever be called once. + +**Return type** + +[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)") + +### disable\_locally + + + +`disable_locally()` + +Create a context, during which the value of the dependency manager will be `False`. This means that within the context, any calls to this object will behave as if the dependency is not available, including raising errors. It is valid to call this method whether or not the dependency has already been evaluated. This is most useful in tests. + +### require\_in\_call + +### require\_in\_call + + + +`require_in_call(feature_or_callable: Callable) → Callable` + + + +`require_in_call(feature_or_callable: str) → Callable[[Callable], Callable]` + +Create a decorator for callables that requires that the dependency is available when the decorated function or method is called. + +**Parameters** + +**feature\_or\_callable** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or Callable*) – the name of the feature that requires these dependencies. If this function is called directly as a decorator (for example `@HAS_X.require_in_call` as opposed to `@HAS_X.require_in_call("my feature")`), then the feature name will be taken to be the function name, or class and method name as appropriate. + +**Returns** + +a decorator that will make its argument require this dependency before it is called. + +**Return type** + +Callable + +### require\_in\_instance + +### require\_in\_instance + + + +`require_in_instance(feature_or_class: Type) → Type` + + + +`require_in_instance(feature_or_class: str) → Callable[[Type], Type]` + +A class decorator that requires the dependency is available when the class is initialised. This decorator can be used even if the class does not define an `__init__` method. + +**Parameters** + +**feature\_or\_class** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *or*[*Type*](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type")) – the name of the feature that requires these dependencies. If this function is called directly as a decorator (for example `@HAS_X.require_in_instance` as opposed to `@HAS_X.require_in_instance("my feature")`), then the feature name will be taken as the name of the class. + +**Returns** + +a class decorator that ensures that the wrapped feature is present if the class is initialised. + +**Return type** + +Callable + +### require\_now + + + +`require_now(feature)` + +Eagerly attempt to import the dependencies in this object, and raise an exception if they cannot be imported. + +**Parameters** + +**feature** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – the name of the feature that is requiring these dependencies. + +**Raises** + +[**MissingOptionalLibraryError**](exceptions#qiskit.exceptions.MissingOptionalLibraryError "qiskit.exceptions.MissingOptionalLibraryError") – if the dependencies cannot be imported. + + + +`qiskit.utils.LazyImportTester(name_map_or_modules, *, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/lazy_tester.py "view source code") + +A lazy dependency tester for importable Python modules. Any required objects will only be imported at the point that this object is tested for its Boolean value. + +**Parameters** + +**name\_map\_or\_modules** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Dict*](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*,* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]] |* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – if a name map, then a dictionary where the keys are modules or packages, and the values are iterables of names to try and import from that module. It should be valid to write `from import , , ...`. If simply a string or iterable of strings, then it should be valid to write `import ` for each of them. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if no modules are given. + + + +`qiskit.utils.LazySubprocessTester(command, *, name=None, callback=None, install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/utils/lazy_tester.py "view source code") + +A lazy checker that a command-line tool is available. The command will only be run once, at the point that this object is checked for its Boolean value. + +**Parameters** + +**command** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *|*[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*]*) – the strings that make up the command to be run. For example, `["pdflatex", "-version"]`. + +**Raises** + +[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.12)") – if an empty command is given. + diff --git a/docs/api/qiskit/0.46/utils_mitigation.md b/docs/api/qiskit/0.46/utils_mitigation.md new file mode 100644 index 00000000000..d8f435a5207 --- /dev/null +++ b/docs/api/qiskit/0.46/utils_mitigation.md @@ -0,0 +1,37 @@ +--- +title: mitigation +description: API reference for qiskit.utils.mitigation +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.utils.mitigation +--- + + + + + + + +# Measurement Mitigation Utils + + + +`qiskit.utils.mitigation` + + + This module is deprecated and will be removed no sooner than 3 months after the release date. For code migration guidelines, visit [https://qisk.it/qi\_migration](https://qisk.it/qi_migration). + + + + The user-facing API stability of this module is not guaranteed except for its use with the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") (i.e. using the [`CompleteMeasFitter`](qiskit.utils.mitigation.CompleteMeasFitter "qiskit.utils.mitigation.CompleteMeasFitter") or [`TensoredMeasFitter`](qiskit.utils.mitigation.TensoredMeasFitter "qiskit.utils.mitigation.TensoredMeasFitter") classes as values for the `meas_error_mitigation_cls`). The rest of this module should be treated as an internal private API that can not be relied upon. + + +## Measurement correction + +The measurement calibration is used to mitigate measurement errors. The main idea is to prepare all $2^n$ basis input states and compute the probability of measuring counts in the other basis states. From these calibrations, it is possible to correct the average results of another experiment of interest. These tools are intended for use solely with the [`QuantumInstance`](qiskit.utils.QuantumInstance "qiskit.utils.QuantumInstance") class as part of [`qiskit.algorithms`](algorithms#module-qiskit.algorithms "qiskit.algorithms") and [`qiskit.opflow`](opflow#module-qiskit.opflow "qiskit.opflow"). + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [`CompleteMeasFitter`](qiskit.utils.mitigation.CompleteMeasFitter "qiskit.utils.mitigation.CompleteMeasFitter")(results, state\_labels\[, ...]) | Deprecated: Measurement correction fitter for a full calibration | +| [`TensoredMeasFitter`](qiskit.utils.mitigation.TensoredMeasFitter "qiskit.utils.mitigation.TensoredMeasFitter")(results, mit\_pattern\[, ...]) | Deprecated: Measurement correction fitter for a tensored calibration. | + diff --git a/docs/api/qiskit/0.46/visualization.md b/docs/api/qiskit/0.46/visualization.md new file mode 100644 index 00000000000..02e5fd0ca03 --- /dev/null +++ b/docs/api/qiskit/0.46/visualization.md @@ -0,0 +1,245 @@ +--- +title: visualization +description: API reference for qiskit.visualization +in_page_toc_min_heading_level: 1 +python_api_type: module +python_api_name: qiskit.visualization +--- + + + + + + + +# Visualizations + + + +`qiskit.visualization` + +The visualization module contain functions that visualizes measurement outcome counts, quantum states, circuits, pulses, devices and more. + +To use visualization functions, you are required to install visualization optionals to your development environment: + +```python +pip install 'qiskit[visualization]' +``` + +## Common Keyword Arguments + +Many of the figures created by visualization functions in this module are created by [Matplotlib](https://matplotlib.org/) and accept a subset of the following common arguments. Consult the individual documentation for exact details. + +* `title` (`str`): a text string to use for the plot title. +* `legend` (`list`): a list of strings to use for labels of the data. +* `figsize` (`tuple`): figure size in inches . +* `color` (`list`): a list of strings for plotting. +* `ax` ([matplotlib.axes.Axes](https://matplotlib.org/stable/api/axes_api.html)): An optional `Axes` object to be used for the visualization output. If none is specified a new [matplotlib.figure.Figure](https://matplotlib.org/stable/api/figure_api.html) will be created and used. Additionally, if specified there will be no returned `Figure` since it is redundant. +* `filename` (`str`): file path to save image to. + +The following example demonstrates the common usage of these arguments: + +```python +from qiskit.visualization import plot_histogram + +counts1 = {'00': 499, '11': 501} +counts2 = {'00': 511, '11': 489} + +data = [counts1, counts2] +plot_histogram(data) +``` + +![../\_images/visualization-1.png](/images/api/qiskit/0.46/visualization-1.png) + +You can specify `legend`, `title`, `figsize` and `color` by passing to the kwargs. + +```python +from qiskit.visualization import plot_histogram + +counts1 = {'00': 499, '11': 501} +counts2 = {'00': 511, '11': 489} +data = [counts1, counts2] + +legend = ['First execution', 'Second execution'] +title = 'New histogram' +figsize = (10,10) +color=['crimson','midnightblue'] +plot_histogram(data, legend=legend, title=title, figsize=figsize, color=color) +``` + +![../\_images/visualization-2.png](/images/api/qiskit/0.46/visualization-2.png) + +You can save the figure to file either by passing the file name to `filename` kwarg or use [matplotlib.figure.Figure.savefig](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure.savefig) method. + +```python +plot_histogram(data, filename='new_hist.png') + +hist = plot_histogram(data) +hist.savefig('new_hist.png') +``` + +## Counts Visualizations + +This section contains functions that visualize measurement outcome counts. + +| | | +| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | +| [`plot_histogram`](qiskit.visualization.plot_histogram "qiskit.visualization.plot_histogram")(data\[, figsize, color, ...]) | Plot a histogram of input counts data. | + +### Example Usage + +Here is an example of using [`plot_histogram()`](qiskit.visualization.plot_histogram "qiskit.visualization.plot_histogram") to visualize measurement outcome counts: + +```python +from qiskit.visualization import plot_histogram + +counts = {"00": 501, "11": 499} +plot_histogram(counts) +``` + +![../\_images/visualization-3.png](/images/api/qiskit/0.46/visualization-3.png) + +The data can be a dictionary with bit string as key and counts as value, or more commonly a [`Counts`](qiskit.result.Counts "qiskit.result.Counts") object obtained from [`get_counts()`](qiskit.result.Result#get_counts "qiskit.result.Result.get_counts"). + +## Distribution Visualizations + +This section contains functions that visualize sampled distributions. + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | +| [`plot_distribution`](qiskit.visualization.plot_distribution "qiskit.visualization.plot_distribution")(data\[, figsize, color, ...]) | Plot a distribution from input sampled data. | + +## State Visualizations + +This section contains functions that visualize quantum states. + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [`plot_bloch_vector`](qiskit.visualization.plot_bloch_vector "qiskit.visualization.plot_bloch_vector")(bloch\[, title, ax, ...]) | Plot the Bloch sphere. | +| [`plot_bloch_multivector`](qiskit.visualization.plot_bloch_multivector "qiskit.visualization.plot_bloch_multivector")(state\[, title, ...]) | Plot a Bloch sphere for each qubit. | +| [`plot_state_city`](qiskit.visualization.plot_state_city "qiskit.visualization.plot_state_city")(state\[, title, figsize, ...]) | Plot the cityscape of quantum state. | +| [`plot_state_hinton`](qiskit.visualization.plot_state_hinton "qiskit.visualization.plot_state_hinton")(state\[, title, figsize, ...]) | Plot a hinton diagram for the density matrix of a quantum state. | +| [`plot_state_paulivec`](qiskit.visualization.plot_state_paulivec "qiskit.visualization.plot_state_paulivec")(state\[, title, figsize, ...]) | Plot the Pauli-vector representation of a quantum state as bar graph. | +| [`plot_state_qsphere`](qiskit.visualization.plot_state_qsphere "qiskit.visualization.plot_state_qsphere")(state\[, figsize, ax, ...]) | Plot the qsphere representation of a quantum state. | + + + +### Example Usage + +Here is an example of using [`plot_state_city()`](qiskit.visualization.plot_state_city "qiskit.visualization.plot_state_city") to visualize a quantum state: + +```python +from qiskit.visualization import plot_state_city + +state = [[ 0.75 , 0.433j], + [-0.433j, 0.25 ]] +plot_state_city(state) +``` + +![../\_images/visualization-4.png](/images/api/qiskit/0.46/visualization-4.png) + +The state can be array-like list of lists, `numpy.array`, or more commonly [`Statevector`](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") or [`DensityMatrix`](qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix") objects obtained from a [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"): + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import Statevector +from qiskit.visualization import plot_state_city + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0,1) + +# plot using a Statevector +state = Statevector(qc) +plot_state_city(state) +``` + +![../\_images/visualization-5.png](/images/api/qiskit/0.46/visualization-5.png) + +```python +from qiskit import QuantumCircuit +from qiskit.quantum_info import DensityMatrix +from qiskit.visualization import plot_state_city + +qc = QuantumCircuit(2) +qc.h(0) +qc.cx(0,1) + +# plot using a DensityMatrix +state = DensityMatrix(qc) +plot_state_city(state) +``` + +![../\_images/visualization-6.png](/images/api/qiskit/0.46/visualization-6.png) + +You can find code examples for each visualization functions on the individual function API page. + +## Device Visualizations + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| [`plot_gate_map`](qiskit.visualization.plot_gate_map "qiskit.visualization.plot_gate_map")(backend\[, figsize, ...]) | Plots the gate map of a device. | +| [`plot_error_map`](qiskit.visualization.plot_error_map "qiskit.visualization.plot_error_map")(backend\[, figsize, ...]) | Plots the error map of a given backend. | +| [`plot_circuit_layout`](qiskit.visualization.plot_circuit_layout "qiskit.visualization.plot_circuit_layout")(circuit, backend\[, ...]) | Plot the layout of a circuit transpiled for a given target backend. | +| [`plot_coupling_map`](qiskit.visualization.plot_coupling_map "qiskit.visualization.plot_coupling_map")(num\_qubits, ...\[, ...]) | Plots an arbitrary coupling map of qubits (embedded in a plane). | + +## Circuit Visualizations + +| | | +| ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| [`circuit_drawer`](qiskit.visualization.circuit_drawer "qiskit.visualization.circuit_drawer")(circuit\[, scale, filename, ...]) | Draw the quantum circuit. | +| [`DefaultStyle`](qiskit.visualization.circuit.qcstyle.DefaultStyle "qiskit.visualization.circuit.qcstyle.DefaultStyle")() | Creates a Default Style dictionary | + +## DAG Visualizations + +| | | +| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| [`dag_drawer`](qiskit.visualization.dag_drawer "qiskit.visualization.dag_drawer")(dag\[, scale, filename, style]) | Plot the directed acyclic graph (dag) to represent operation dependencies in a quantum circuit. | + +## Pass Manager Visualizations + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [`pass_manager_drawer`](qiskit.visualization.pass_manager_drawer "qiskit.visualization.pass_manager_drawer")(pass\_manager\[, ...]) | Draws the pass manager. | + +## Pulse Visualizations + +| | | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | +| [`pulse_drawer`](qiskit.visualization.pulse_drawer "qiskit.visualization.pulse_drawer")(program\[, style, backend, ...]) | Generate visualization data for pulse programs. | +| [`IQXStandard`](qiskit.visualization.pulse.IQXStandard "qiskit.visualization.pulse.IQXStandard")(\*\*kwargs) | Standard pulse stylesheet. | +| [`IQXSimple`](qiskit.visualization.pulse.IQXSimple "qiskit.visualization.pulse.IQXSimple")(\*\*kwargs) | Simple pulse stylesheet without channel notation. | +| [`IQXDebugging`](qiskit.visualization.pulse.IQXDebugging "qiskit.visualization.pulse.IQXDebugging")(\*\*kwargs) | Pulse stylesheet for pulse programmers. | + +## Timeline Visualizations + +| | | +| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | +| [`timeline_drawer`](qiskit.visualization.timeline_drawer "qiskit.visualization.timeline_drawer")(program\[, style, ...]) | Generate visualization data for scheduled circuit programs. | + +## Single Qubit State Transition Visualizations + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| [`visualize_transition`](qiskit.visualization.visualize_transition "qiskit.visualization.visualize_transition")(circuit\[, trace, ...]) | Creates animation showing transitions between states of a single qubit by applying quantum gates. | + + + +## Array/Matrix Visualizations + +| | | +| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [`array_to_latex`](qiskit.visualization.array_to_latex "qiskit.visualization.array_to_latex")(array\[, precision, prefix, ...]) | Latex representation of a complex numpy array (with dimension 1 or 2) | + +## Exceptions + +### VisualizationError + + + +`qiskit.visualization.VisualizationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.46/qiskit/visualization/exceptions.py "view source code") + +For visualization specific errors. + +Set the error message. + diff --git a/public/images/api/qiskit/0.46/circuit-1.png b/public/images/api/qiskit/0.46/circuit-1.png new file mode 100644 index 0000000000000000000000000000000000000000..1c2f70894dfb00cdcdd33915fd0f49f87eaa54bb GIT binary patch literal 4978 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 KL8;!u$iD&O7?Ab= literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit/0.46/circuit-2.png b/public/images/api/qiskit/0.46/circuit-2.png new file mode 100644 index 0000000000000000000000000000000000000000..2184a3d1db1b8be3cd5fb4e7a207ae02f9c1957c GIT binary patch literal 3885 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 PUsu4?5OKZIz%Ay#$2BS` literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit/0.46/circuit-3.png b/public/images/api/qiskit/0.46/circuit-3.png new file mode 100644 index 0000000000000000000000000000000000000000..70abaad117f4769f0332920b846eb7ed88dcc24e GIT binary patch literal 5628 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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit/0.46/circuit-4.png b/public/images/api/qiskit/0.46/circuit-4.png new file mode 100644 index 0000000000000000000000000000000000000000..d7c78dda5565f4b92fccd801bd519bedc15471f9 GIT binary patch literal 27444 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℘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 literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit/0.46/circuit_library-1.png b/public/images/api/qiskit/0.46/circuit_library-1.png new file mode 100644 index 0000000000000000000000000000000000000000..72bcbd480c5cbca4bea83633730ba766ea3d2463 GIT binary patch literal 5904 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 B_(K2y literal 0 HcmV?d00001 diff --git a/public/images/api/qiskit/0.46/depth.gif b/public/images/api/qiskit/0.46/depth.gif new file mode 100644 index 0000000000000000000000000000000000000000..4437049fc8829bce63ab0cd9d5089b3b7011cc55 GIT binary patch literal 2874095 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�okcZtFf{p1hw=P5GV zVFT=Ol?3CVrD5EhQVL4<;;&o=8*m5N9`Z(>#w1{fU7mipJ-mbcq5^kX}P>uJ9xfJ8b!-Z7q_d6wfT=1m2Auqu#CxTrwOi0!-8fnU2 z@4Pa-G$aNJP7{Jid?%wgKa>g^MPDnRlacLXuNr)C^UMO3lTm!I&=hVYY*Z&XVUFY@6= zW>LT*w%~KkN?WSqZw)5m$i+w`nGU-kI8#Ee44zd~%INhI3(n)x0%Fum)y-lCL--Lm z2=xdP1mYd<5s`*(Zj7L09}5wKro99tR3#BG@nH<=JPx{tVhD|4sJ0W!+iED;sy)VO z5GPF%hye=*G^+DdZEbr(wkFw%70bpXDfN|;??$6naJM_MF77f?!!>y&dNXAKliiv@ z>!Sv4)lFUl30@k2D^%~0GCK1Weon1grD`-|Rw#>lmPbhVX_(gjwHCkxkhK>>)IOb1 zinBNb*^GNE-akv6>kkDXf~VBysiB0W(9dzKzt|@|L&Eh1XokXP(hY}0Wf2o;8dEp5 zZ+y8n@?y$s$wKu(d|s?qdC&o==xOg5n2omMIL23h?fbYqQD!7yOs8@YkgeDTdYDZ# ztf;03h_+|qN5lZ8ArC*)`=ubCj}k^K%AXzK-pvg|9cYiij}7>U6MG0A5-@DW1^zRc zX`=h#yH0hM0zeoFv_{a?Xq~lC!Si3+=5fc_8F2xdU_|XpFJN*l@BrZQBsK?JGjBfwsvL|K5q9onk$Z*a?US%kya2g=YPw3997; zUCM{~aOcqHV@;~r3m~0yWW2A;!lJ;Nd>a30hjJ+WNDIQeE!^ zP`pqW{f;I(>?dSg2wA6CLZmbwGK>rzMp_LcU-TdoX&}qH>S6p#VaUYc4 z(fk0mIRO3j>b&L({m-#hlEU*eWLm3P*cFO9+^|)ex6M{j>@GrveW`{-ezb>0mn1qO z5ZWbeAyKs!>$RGw+hfc0DGPr^x6C~8ZX%W%YG)Gl8iqZYk4zngh^cLi3hR8(BtS2b zSekIG##$SfO(MNdH$v~$Kl0RX{Txjr#$L;}^5&16l*a4D7ZB61%3!j1dTJ5!%5pm* zeJCCh#j`PW{>eI7G5XFJA#CAF87-4#b)Ro#mlVE!0j@9h`7(UUK7T8Q5l+I{!C(H`PJXY_tslu3|8y-Ul+KHwaZ34 zBg8IyhD6UH$7R;!!B}cypd{jGqTt0)|F6;3TlKisumZTo9X124EhDcjlZ-8c%(vnQ zoZ8P4>L%OU)VSEa-N^_H^4^`}AS}H?oABIdWhEQh1SA3JN4j8Y8d+N*Z96ohhk4?d zWkh~Z&*Yb54()i z)i8wdwT*QB-s?szJrfYrd^XyIk0hx(&vH-xmQqg|!jb`rHR#H>H!XwgI_K^pAu?QT z_GVaN3}4JQTEmSt8DRS;y#vasc!^CUlcGp1ig$Hv2{*Zv#fI@N;7}KVgsZ{V2F)8hBaA<@5itvc*s zi?JP<2M33$A00zi<_}j$7Bf;gcp+FY7)=r4v!A54$Z8?&8r6lz6pL`Os*`kNQ~(nD zHX+InW&2>c^dti3;|>7x0s=x_thpg^Ve2O|i4w|!#CNV2+KQuo=?cGXsY&Il#hyM# z?QD;n1!P6N$#Ui1bejbx*aQw^CL(KBF6-E@&5u%U(#H zv{#suy;z=m5>+${;^j9ik2^me6B%TXh>4iSGP;Wi(Ju78uF!*JHZgu!XR;d+?{kEF zyuG;hP@B=O@FMqFAr`|BJ(EK}FHi0Z;9P|D6QdPyiWE4>BXT9AFY>#nO2Tm2w0P9D z$fU-nCUyJg_TmNJ5y6*S2iFn-o6&&pk}sYK$^#dI6L`kJQsgkaxf^xS+BQ}snBAwc z79nFi+m+{;j64cCa@4ZiW+Fe9O1Mn6{{BGa8kRqdA#2z%6y}Si z0A^}PB=Sw~x$Va~zODMcOA;+-e9LvQ8#gs={mjhD6Und=%5a2WP>t|i3GGWr@W_lq zlOTlYU?g(@yFsn9Y@eg_7)35~5LGnV(d!razfIDFZ^L?W#UmtarxabNkpdCE&Vg+=q!DjVZ0=| zDBq(<->bXi(YU`tzen#5Ga-m4%YKKapIGsYB-vg$JrRhE`rVyTGjksHVkO{B)SGx7 z$CSVKK}{3IhcWL)!z_-l-m6BrUirU2#KA%OR93XC2LqO5zDp+~@t@BV`G0Q6@?j(?E4uj{cP01!4IGdn#HlZ1p6!miq=O%X-NrVrk#$!L8|DeAN6RJWtZ z6(^gLHa4a{o(6uMr|*0vAC)EONT8PPIyRLjC`|2j{DW<-P(F%~$0f}^Uql63ZN>@f z2NRR$!Mq+Hs~d%Ix8QIajItrYMEZHwx~*Fk^rlKU;6YBi(fHzE`H!9HuGw<3azb<2 zuO>*i~7mS zOf7XR7*DcCKRj18kG~*(I)_E=)siUQFL-tL{Sd>mWP{^ZZ2~SW0s+JTO9LG?^^e5M zR`nr@g`ihgG{dB-Do94CWd(_UUT_npk}T%=cKLwmO|%$ev`WxIwgHU5I8PB<3K4<@ zhnOrpLu+PcNA4HxEjo?!EL-TkCK<^xu-rQ$4td5<7!uVXt;?9Er>>?C`+(Kdn z0FXwPE_Yj_mu1|=^4ry?U??8A)@_c|e^);$bn&R9J9LOUv5+@{&A6BJH44lLd1(n^ z@OgyFR9df%+G8kLP#_YMTmZufZ&`!hkpxSP`tAj1m7<@|{>4zVNL!@=J#0q_%w{Ot z4~6ri(BAz5lib838u7;D?MgI;Kx|xLLrz~pqJ17+%1ra5N`>ll#&PX!$&*^h);!@%?cKy!1M272evOW$^;RvT)?NI!sw0XD(zwZ2j)jLOzy{TjI6(MF#x1q7!+Uf?%@I3^J8SI*NIE8YaLmiQ>d3on*gO}08`D1^u)Ilc{VfzP{YdPuiA zo7_2) zBiwnK?)II1G;fnOGbJyz!=CH_r_H9Z6ZjKw3D7eskem1$B|eJ8SwM-hSSfUo>=o}Z%p)@C<@?$I>UosHd(p1|GOoK>vyoR$ z@VXRbva$(ZQeRme>NMg$jja8h6aNrK00uWbhzNy(vhs&u(*wX8LfY&spiu0Oj=1CP zShNdn_I(eZ#y`k#R~oM`&>S95oO5#-pPa#}B}xg-6jDue(J0_oKUvHr@4@hV)y>Hi zb2fjkSAJ1fHho?ww(4+~k4CkQ=~C%jrL;JO?~Bh3v4`uq9CkiUDgs=ZR4^~$oP^oF zxit0zbn3lYm}2qgfw6CTN^YN~2WYN=JuTR6^o~JUTl1meEG;!}0dL4C-D1E2JN~Ll zd1{)P=~Kd7zYf~HjHrnDqbR;%1hwg6)e|;V%0e~j#z4%$dcm3uak~9H9eUgaH%+m|&(Svsrk%Tp0~SGd4BNjt+5kkJ(kKtYCRehE0YDKf(|UqAFdQ5}?2CA7|s)o%IDEZ(K7{4G$8 zu$S3@H|8YB_V1Eo*`Xr$II!KK)IDTrA8ex{y% z=>@<2nFR%xd~a<<=%$9)kQTK5_T&7JEu7P4SvAHq|y(^UNErwtrQhR zj=Kr=kVPmk)06oWk*($51jvE7WigJ-$S4p1`VZ<4IhKnyRQE{>9Yejp!G}c&lp`;o zW~W^g^37ef!2h5s~A<%kcX_>rGDTeR?C=WW~0Ush=VB}dV)7=lT6C-5z`^uvk0jsV(;N4fTKjBk2AkRuFc~Ypw7s9zmfyC!2b<9rSdxYl*M>Tn zm2<1g4QrNaWU+waO0|g#t)<3go%Zp1F(e@`jjM-@*It;E4^g+VUfz8>e6Tn38Gc1N zM71vOVa7_auI;WrWLq8%&_(R|DXY3a^uw0 z0}s40D`%RU4oVqvl~4rvet20W3+`qnYsQd59V#~t`pj%Omn*WZ9l9v91s_a@+#9)d z4!PYcMye}50XQKB9O#``eQ&?9lZFEnQ3lPUgZNBq7=o{(8~9u5yY~`ZzfoXWeIbi4@Iem1MNBfSRzQ05AIqO!evtn%F*; zxI2U+{G?L-ut9$)w+%7~#o}fGczzjpp5UAv!=5v-=||7iIH3uXpGz`1(TQ_X%d32I zP|ghwRggskKdQT`xv?qfx~M@Av5KiUcd>>RxH@o7(SxI6pW-GDLzno|4lDe=@6=s5 z)YZwS_$eXg&skL_N)!!CImSYnG;0(Z%XJ{9Z8Ru$>c{;E1*8W6omk1!SnEe3Fv`IV z1!aRGCxgLBEVP(S)rxs*wH+y7vUU&~H4j@7&@x3)$pPgAd+DAK@BkRSSNyyg$|QS^L2%xCf8bfb2_Uci;ukJJ>>BS7(dFYl zrTNV}`n)P4W~q8;I)|OYD|D?F$V&d%-|RFUBs;ZK2UfwGUP~? zLe~?SMF1YnQb-81h}H8O07ZMKMN0oFVZ?H9oeo0ITKz&9%=>nq=kPm$SPtpRzi?C5 z9H(&m!5&Sv0UqY_(|?LX&x_YxY|hQjH$dkH7o1zwiU$`LZAotH zFU^ND!oiIQ>_EVuwo4o_092S;&MSmz48-QktoxkqNJ5d09AjgIIYPDeH)rPE_k=@M zy7A*UjCR>SB3Ibd4WK-u8JBv+xrVPmGmj*jBb1$*k&l+?`9 z!VkOf#C2?D{nUVaCNM4Qqx9g`vsqI~YqFZ1e_J{tQRuA(=EEQM@f2_7Cc>eXtmmUu z0@hygwp`*(c@@IF%H_FU#<+P}kwcoX`tk?%>tDsIzM|B5x`cPE&x=+f!azV9Q6epT zY)^6|MW6EHzF_YT`TTzocAsBO{L#PY6B0-vfh6=^Llfy8)P&v%MVhEIr3lhHO6a}! zDj-dI?`ncb2PrB@Q9wkBg{GjQIegFgox9e(Pwsv)f56O|nf3ncyJHfe57o(Z9J3>gRg82COkz^v zV_WAGRC6ei+FB0rig=+h8ut*5gWC1;R|Cw32@OsAN!1R9zW71bD=Y1+8UbWn zr&;llflDla6;Esb12jOSI=8p#AW{>%E*5{8$;p{-a6#3)PRitU>$(oGT|0dNoQgj< zLGpI5An#&Ro{#(M2~wia9wbC3j@H?q1{$a(f}`mK*cS)to5x(r25-!Hoj4whssGgM z?PM_jNduX@!;)gb(C(?K$!gM#W4uU(alir+y&2g36@b47EKP8K+DygF;4iX786pm>WR{0f;dG9f?F6jQ976r3weqb^`o)67Cobdoc|2 zgt?2b(%e6tkheOE^fHiTHaE?{Azu@b!@((wBwE91&5sFJZs6iv0Oxr{!7N~+K@4MW zlz6ZY@)gDJ=KG+ed&v&bK3#B4Kn@^fQYm+VM9V2Ja`Y32@QU-or5E#NZ=Y7|;zS_r z;D(tx!IMwyXIZD(QHtFW`2ZwAxpW1G%mG}XRnpJ51fp7KgF}4U`r`Awb(fN#YBv

h}GjPha2KophxFqzbUL}%YxcJqiX-K1P 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

  • lJ#GT;3{^ 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

    oA1i@H~V4G6bLey&;1Z@lE|HEHmHs zyq;aUqPOme@u#$hAjdA3IXgt!z;`P+cIta*?7^)1{l?8!?*a_*_ozmbxSDi#W4Ovt8waRNtZ&?$mdyDuD zk2+=SQCxH*tqqA)jdouZej8EIn`mOUBjorNEGSyfaDGv4(O#0+RQKBsN?fk^8sj`A3r zl+3mQFIl7huThN?J3Xu8%^ZFw8gFD3$p55_h&cH)-m!N3l-t8jYzG4K15VyN>7m5| z+d-W{>J>^v?`{nV8yGKwP5Aw==Q^puVj|ztpaJ>)xtdtja)pweD^6?jpYgByGYI*2 zX0-Ky2h#C-?I=@r=dD>$s=(ZQ6uJyl3@Wqg6~Wg45UV}k>|AVf%_?MwOVFXaNgz4Bfj zXQ8Pb-qp`(TEz<%YiKjm!r z-|`cBN&PP)foN^zl>##SRe4ZN)(?2y@qw)T)@KzxC*q7PJI1qHeatf%V$*S-lGsH4 z@KQc{b0C8zu^^=91-Tr5%L@40FFNGxjL1>%^@WOuste-P>f+;mwE9FU&6X(8cUYeM z%F))6?lLO5t@Dm1@sE1`wyhndm{2AyX_YczUkp3XNuTgLA=WG{{}%8h`SZNwjBF{m>7>W&ky_bB6`T*kwU|CpxP>T zk18S8)u=nrvnx)l8!;@Y{5SrI4?RLgDw1;E`Nuoaa%WM51lJTKN@^96m1oNO^{HF+ z6UKz6z6lAWWkiuRV&OFaq|}X0T}a9d5nRpH{EJ3nHU1r^Wa8Jv6@pj<2VvotC&_J2 zH1h@eOk5cFb<|)t+K0A10V4q!X$qGnJ)(?F?}oOQ99Uz6?=-yNSom!G-6EaZ#);QRH;LeGO_X zyQngA^D+qOu*|hlLBBGZT{C$Wi3d-~gl{g509V_=#TgK4pe*{zG;Quk+uSTBjx6!G zG#2}?_wCAe6Gh^%@Kp?+d@Y}>!w$~G5Z=3LOv;08%fG2VM(C5~c)O$(_~%$Ba;ud> z9u&X^cVJ#Q;$grmy;qu84 zkjXjteNBpwQRHJgFx*bA(o!}PM=TS^L*p)57M{?w-@-$qxw$;IE^Y#;%L*P(YOjTm z82JL_2C#X6+>j^Oa{?o~hA6v?=$`~?FA?<(J5%Ca^`f}^C|v{723p0Q8X$N;w8 zLa~a4cg!`AwpQan@cAh6H9L6EDH)p#)tCWQ$RtO#0jx#~0BsQKOyae}T3+@A)H7=3 z%^0@8hSC(0brf-QKwpO+7Dn`_rFI84w$lj$AQV4JjI;qigTf9>b(kG#&rZGn#WOa) zM!!U?PjzRD3%D5z1N)IQ`*xDqlV)#3&H&`N)11|v9+P`Ls}A6_E8xL2khzB7ShWw{ z=yt3k>al~noZc?qfvFeO+42E=f0~oAFx*x5q)@)SwxhHx(uuL?)`Ql@BE2|FVJw)As z_`B{}{lnVE^~gCGsH3G3%t00zT55y|md|NSAM18X#t*jMPA~gIx9I_nGw51M=ovMw z{Q?7xVJln!@@)+Hpur$PY_HI}%Abf{VnZD1b)pd#9_>%YO9o0|1UK8ksf&Om9Mk+9 zJkGZTc4ZL9K0xaCf?lhLTc<<~OTNhm;BZ|U^?jav1McfoCs0NgfMS^MKK-AHw;H2& zfA`L?li2`}YJfuQI^1x&gm=2aZw{WzPV5JQGoy&5t)q~CV&wS-?|Bws_}bSD+H;Cv zO9rV@aCkGO+WxRhX@5YxtWNCk-bb=m3l_tfkD8h7heG6H6hUoeFt~kddF~t>HwRa5 z$mY|6)`F(Q%OHbTGWb*{@UiL2xv9Tc}1_=#o790Bc zG;d;?V3U|J(V0rFr8BBRYKx>-;iN^d7r#f$saguSo26%#=!U8Z z&&l5Rne+as>bt&egIyQ|&8ax!6LpW?v79y4g4)WX$WedeaO~OTxRT(yK9fXpsf&_B z%rtm@IpEjOeXm*JV)B1cC4=k(UwZO*b=%i#pD~uzk=V!_$gYerle07wgkkc>}ifET9lp-BM7fsO+NM&@Y=?SV*43ER^W6);L463veg56jsa=&(9He zxz6orE@zf-|NgfAYQTIR3+oa9RR6|=`BoG1SqFK%nKWQo6marMiCQRLe4 zfMjpab#mK*U)M+&14^4#w7!GL9z49Byg0M%NCQsZfn^rL=_5=dc#0{>EL zBNoZ;p&MV)w~gJIxoe|FY5pTpwd*N-L&UtzpQtOm%@1;`=O&{gdCM=PtKVCQOjLKej+TYj_wGATgOT5n| z^*MzbK42>jzkVo*+O6XtcKW4G9J1|b3rrfX9P*Wm&L{~tJv_Qp)&`hVdtFck>O z0-~V)PYq*6ftdOK2Zzal`1nBlY9MiAkjy>MT}P0LCrDi#q!$h{i36EifbL;I4n-i> zN|0AQC?F6N&_+ftn4r3rpu2})e1c$Smyq!ZAx90Nq!baI7ZFzgVB?~Uf{{W@Ebu4K|+Ouup_z2ZV)kQ>N;g*2N4IjoUBEl<=PoEEyk1qyv z1BV6jPu!4UVLDA=v-le|EIb<@A-MdQ{qbWlt0?R6sDJ;#VR1SHPeeYYq@<)tJ-AWB zvbeJTQ^Nu^{)59za&F+Tl6wTt@A^E~!9U-?m$v;64&$%6QNvoC30wc+|0Bab;5#%Q zcLd=(?{xl84FkQJ#*YY({0D~_r{0iZv%!RK#ooTH#?PJM7Z(>-%yKs*Z``nr&Bvgf z`TxOT(w`3x55FZ4eEa!7ILxi#EWGnSI4phW;^N{*+4RrW#moNn-_v`4R`J*GkN%zg zPYpB1>svvA(^#YakB2!aRdkbtD_qmKu`~$S3 z){*yZy~RuSt*IX<~Pi^@ZGRD=AoT*6vYF z4Qp6?a59}K9}vfme)Dh4mUPO|p;fesLjK-Ms8M09XJm(E>$kTPHOBSJg`Li> zMcy8{x!RrIcJeq@_P)Wyjt}1BV$)6hA35z-=DP4UO?KZhta$FG_snvQ$9Z@4rN`Z` zPrhrvmAt=*XD0u7H7(U)UU<~7{NggNRo3UZKHHbg0v4~&P0|ruK825GsEu_;w*rd; zCwYRcBH$8Ih5>iv)$Ibie*_yn%$u)d(B0Ysv$|>zeA-Ds3sUDk-5+RY)ottvHV(ft zbIUG?mo|7I@;ayHLmKhlE~6+ha_;;{+O)X*m^YTM?d|wja+Z=w&$*q<=m#&db(v|Lm5FIb&WW3JnwVv+5r z8zbeN&(IUNtjI)MtvTj#vPjuxo2C6W%(V)WT#SzklCe)Kf6}v%^I*PqU$Z!@r>KT= z^7leSXDFVRFH$0H30338b5-HfEaUFnn6WKQRbFurhK#eik~wSxNPpjM$zTlQuDYF3 z$5FwlDV3GA`%cBSI5#bh_2oxBG4B_yieZ^Wc9~=K-A;v}2f@RPzsp-W2`rBX;XN|Q zhW7QuV%=%+Y;EzGk8N6<(O3eo_Q}8cZ@vfK=>1A?{Pf8f5l#PB1FHL@0!<%U3k^g+ zS2nawL1Bw2{Hbp^MnhMd+CK%;q>mmK-3s{jz3X;~g}deVa;p=~1&Yy`DILj15lJZD z8zBaD%*PY0**eIPx)kc`_Z4EqpId`$`^gU{P(EIM3xv`~KR0xgcd_G`cl{Zi8=o8K zR>NWV(N1Mk-s&^ed^L;q#xS}-@McQiUteX+IQ^O07i8-4d_>lxLv7h~@E0v}Jkv=t zWybvFKHuF7NtH*RWq+$%-aVYV+rHxc=cxNj)1Tx1U&nt=aF9FKr=t*k<`c(Qv@7N7 zWG@4rdjlm{6$M$1xW9T7uat7!*eooi$1BA(2&7Yq_$6 z@Ch!REdL%boM6VMctaH7!;LYA1{##ZyOh>7US8K_X8M`I2*)aH&|yLuee9QE;li^g zie(%s{lUOqDnCc}qtd_q!~I*NaUqAI4o6F^B7yB6(!VEJ0%cQNdg`lw( zk`wFJ)Q2e#n78fXkwrmizXxL7juLLd_Y2wrMn__ngh)Ua7;^WoyTEjUGUdTO9%g=U zjFJ%3gG%}jK5ZA|cnN;SLuDmrvZt3#8^?8qKIrps_Ah)D@b%v1-u_PFXyDTpr{acvA~VqG9f)s36l={7Eh@%W1jcZp)9I<>hVW8UD9shln!E#~^;g(Y}Rk<2rx+-Q9YuXv&#Y^M{#r-K$ znQgC)wgqSAY`(Wtt(#X_7Oxoi?s8%fy7^a{x+O~7^LXis(rwCseWtPGp68c2mwykc zCIz0*IbKl~T4ly(lnDN%NSMe!_iiO4#wkR6v0ayb=k^u)(RhAn363(YE!F*K;^a}# za7DzZWpI4d>#CGE+N5b-Jn?#vdo9*lv{z1t&;Mk_nz%lgWf|IPnXJBLK?WY-WJqZ@Poer$pPwV$1gLvhBzI#;DKjAQFeP55_!}knJ*%mN%C@`S z59~akjx%8gYpO~R*)2VEDfLf|vyZ<%D352R3`Cm-NIM{F5K=+i?faTv47wlGt<3WG;d(alf|cG| zpO+KG3E!8-RS%;*gEqHLPb?x9rQiC@e2MsO@WaM%=k>?sKTTU_m&HyDbZbHXx>@eT z%P&Sx$YlTHrqUZA$cZaQg66t^-SJBPD#czAyjxSkzx{$@&g_c$8$Kj{k~Ea!R{b~Z zp@EX|4UIrVX&L;&4C>2?noNh1tDY`zjXYHMv7(TF49NHX%N8`R{63raowoPr8nObr z8V(|P9L7ApOZhafYk4s1dD$Ikiv7VXBisA#F@!)uJLH5V&5S|jylAO9w|Ie0%w3#6 zA%(!F_j4Op+mT?KwA|M89rB;v%o$~y6?7$iyze9zk0A4Rzx$@p5OgoONsbszQ5}W~ ze!A}W`(eH~dst*r#n+x93(C%amxXcC41th?mWJP9f6DeCo7*~(AfGO<8b_G!h&hS=vtats+1C| zkHWTiRfv50h*WsS)2oV+$zSBprRNaA0b;`(M)R_CLmCN-0xcZw;MNGT?wh19S$Rps z-8=?q2*SBlcY98@K@E7aqSi-sNA|UB-!IC~JC5ov9_vs+DHPpXDlnAM?u6n(Hyc?Z zQnA;a-k7+MsEoS|Qb1Iu`>P5EhKGtD9Ak8qNdgwVk8}A=b~O%Y1H~@mJa5GkR{_z+ zJcb03Jw*41m7_>9Wa%ZGiOV3J-zkoS;#4NY(nkQwZUiqk0#S*w??f==OMeoHXKM{W zDk?Q*hEPaEQ`6fM*~_?GO4Pk%(zpav1Cf+LNO_I;Yy3ijq{tJPeJqorB-;mOekf>1 zG(k^Pfr29u*7_7NA7R_ckTxM~%^k0EsZplHnEml-q?BUus@Tj95Y#Qm85dPC7LSNl zs-EB<)Q}-m776!D05TGw!u~HO#D;eOtObXqiqKd>!u_AgaeJz3nTeFb5gNu3412&- zcM2~jj3Oh6xaQV&c`|UBv@FGi2toSPu=+_Mxdh*BM?_mWu6zd= z3PB1^h!4JtYY|R8s^NrmASSwFz=R11Vf%PRGsF#4DFnOm$a`+~%mA$3_s8VXsS*{b z@S)T#ZbtewtcTGP`JptxQ0lgQTAgdu5`KvH&uTh;6~1W~M}C$T5X1IeBb{_INpO-s zO}8!r>m4%2n0Eeba^7o8Xup$wqFeO1Grcz{2q8^bJe4+TVZ@Y5LeC5Z;6Q5t8RM z^z4+O*n)v?gg*61nk!ohkwThr-2*)DLEO`fu+8F5J}aRdDzH<%v2Kb8>KJLY01t+& zFOwW?H@edAd!KliAca7SH1fw<9^Dk@uf*&gjq+&e=NAk)uUgxjqT_6bP`bR}9-{`D>O@wq}2=cz!Bf z1@kM1?-E&+5-VT;9$x3ZwW>R075a%)T&Vo&u?q3^7x1%6BEwR65JJTcl2A&b(ozY+ zip%a0X`F(|+^fa$b=5>+i2Q;(YP{7rf|8=dO49jCvV8$%-m1tcNKp%EY-tUsg+mqt zw!%Sjgh=c@b68ISwpUe68ntNT^K8xvSnG@U+GnQ(FTlG*UIwIPR-|4#L^QiZ`lTeX zKwVKO@$I`*lVkufiwQPx9Sq6KKoktE<6V&_QRK{am}>naQ5 z@}VsHsKV8Cb|$h~hdRJ?z0P{L9??opu0pWr(i1~5-;|4 z6_553Y`gYGshL9?)V`J|;brUw4Jj{zA69wp&SK&4l8B(8jJL}R19rwhP3#~9hfsH1 zJ7sI9RaBD?Q&+&fuHd4sI5I@I_LD)zY-^?thQ3~#-40vgPV(pusLYCkLo~_)9`!xmur7b?uAt;D{ZpuGZT?JsncfYkw*RWea2Ofg zo9A9Qnou~eJw(!~ps~|uf{||b08aXPN?@cU9_u;VeDj;LBl z=6ZJzpwJEh>mZli0oSRgf0F@W!y&In{S4M!52Cul>RT7;I;}7bIVvX)?o5#g|UsourvxDa*e40UNy+Rh!CGmtZi$ji+IWuWJZ5X!N>f z3bSg?ks1JVbP&}Hz=sA9exuN#(Ld4%>+m7JWGEx^*qcK@R)_@5*AjFy<$iVgb0m$| z6O>Go_4DN=*LhJ4)&CNijKhJj-fF)$NM~%14F4-Nk1ou&Rt3J6*g29CA(EiEsj_tv zyNBc5;WW+nGDhGapYVd$%uglz0i+B8~LLl3a!&J1< z&uAr6q}&fY3kSY!-pLK0)RzMc`SXTS0D>*f`9Fgupos+Ex2R-j&?#5}7>?+ETc=pv zS2Y94cy(3O{U+lzSa@gwvcOR?emlCyq^0373HksS-NsMO*Om>dhvf?BFogAw6Wi2% zDhB@Qq~qVraYi@1y?$v9m$~b;xD!*y2jg^gOty%X-JNpsje^sWR-{4f z&IvXfQZE+_K7(7&q$?Q?4Vyry37i1B5(*!|6*=y#N5(=TjZ*9>%vpFamp zEqmDjS_caK0^7l&@3;67LfYyTp#rQ^!%Z1!FJ;6oZ0J%4)K*i0;{NGQ(rTn%%~D@p zh3@*gJn+7uk;ij^$h)*u04Hj=ez3d<85$>31P4vyRvk8HMBdA-Zi@e!84_4!u%+Yf zZ|qG4e8^YM$abir!O9yX8km~H*q%??QsUkpAhrN$(~b}02kVScGtpIIy=ZlB;B(_F z-5IzeWgdiMQki@CDG6*5PQ|?ygRl*t(gSwid^|d0bCL&K{^s+h89508zZ(GsI|z!Y zpGy(EVE-I}ZW>IOBlSAP1*Yyracp5Z5o)-{Tmo$bHVkz|Wbu$iFJ3C@W1K4iXM?fYI`% zvIPZ9tk)@t;!(@Qz7cur?@)vs-n%m>>P1Wou|B5LMt%{h0}0}rkGVb>-ELVpXpY4l zoOlBide6Q#o=e;BCWIUl3V+`CdfcfXVD3HDNd8gFx6ZwE&^{vNcG?-^+oOQPqiNVV zc>WOLHxbKTLwKh4b)yrj!;)}(L3+0LY`tuDuvv%=F(ETXD9rdnu)(dU1!z5)`gY=_ z4N-m$boP<1{{zdmph)HRi?C~Iq(>pIkX)}m-F|g$^!Avok?n&5gXlMCdiv<=@H&R~ zof%ATUGI$LKC3h-9gHm{4lITIXc}DYuX(@zd+2e-!sT`hMKg;6%fI!N;QK&j`DOIC zk)K7CAGFRgWao(w8;pyd4ddT`U5L(07T7V=z4Q3hGgxb<)5+@qrmkA=POp|FWbtw0 z=i@E??M~>)+4jYELH3{IKs*Tkf8j7tShm*cT-lJ3Jgdxw;zvy;l_D|sKu7gyDmJRy z2b!Dxf2x#n0rywnBq*?0VuN0F>^k; z*3tIk2iJ-*Mg5>nY7-OJVkv{yXg?@=|r<&$~xe*kbm zkH7W+1(V32j2kOe(pYKGn2<9kDKV<2u35;DB~NbX*k_usLi6tJYc!(KLyUKl6q-h* zQKv6=Xu0Z$Pn%ABHacpfRVM#X&|WF;=H1&TQJv$3SovXG`0cbZWsAeYk( z$2yhTu}wk?bx189)%5=fJQ}M^@6VgqqshG}o7^xwN4dIkC(I1>^izX6Z4bkny1W#w zFh|>TCNy_?)2KLa;;_S1#S9cwT-y}xCgO@yR957^^wX|eXF@c}UuR;p(YaR5^;sv? z8`3CBnS^TD2s4#QNKUiVl2n;YJvF>qp*7b*3B`1l)jRP7ccxhN6m}&M5Ara$Vrl9X z&tz%Zlg4?^6}Y?_JA{;`90gsgUu9u>Vh}A78>r8MBz8&Kue?=qP@1GP3fqB0?hWLa z(DRAgn?%Ly-Eb{kiHc3CLxP}xiO|9h5?x9+xOHJ_)m4@e{8wb6CyRHcS!ud=w0vdS z_oh5oTCFfXA_o6p#wXO^gRqzi{_WtH5>^=5qRXbN$8mk4m@BYll2l8MPa;A#>eN7j zlO3M00}%reiHT&zw2cYnlr@%VOS2On3vrn|c9Go1dOovVmQLIb5l99xu&@spLDv%h_CC0f_J|@-`D|e3>6$&JSMz?L`=e6fRx>147ye<4S3 zA|b-wHaGv6jZ`Oh1lfT_s4xck@nH~-=wBPu@Dc0nz<85F-b>InB}_q3hb%D}O)xes zywngTj!PR$p0FLmz{U;+s)QY=K){4l-#IFTn1rio*iSwxVKBI=AGXDwO86OeGi6s~X(uX&*#uO||*8EcIf zMBv}X_(+Gm(Iu`^THA_8!IvB>Q81xGC2BLmxA3QSo7f{uen$`~YGDjjLmoB{tfHrbTk}qkW=*~z!OuEE^Zc@|^2-G=p`XrT|V5KYn2g{X65Mk+T zi6*}}Mt?T0kud30C%OBPR< zCboo$xPXPK$W^E*#4PDJ2a?KF>aUe8)M6*BH>U~l6Qrk0qasl=P?xy0C6shuLR*qZ zV+nDHKz#^B?}vzK4ick=ETu_KITKm#^npK|$qWyt)Ryp)CIx*7N4Et`mx%ORaFP#9 z>q%35Hbkfnv53WXrd0^u6^&?3>muF6QkQ%VY0YHG`z8pLb?OeNPPM313u!&UuH^p- z9g!F%^Hx>77LBMd(Pvk6dXj+7qr6H5|bhgr77i!#8of}qg&B7@L@ZfaLtBemZSiejih0XC`{&h61{?N z!Ykn>i;laJ@iOx_=SA;lC$btm3dS(knQe&Al~|WxFkC0L>U;AU-=o@iBBB3f5mR0A z+m&2(TS&gKJKHcy4z~dbJK(L4&*jxjGMFU}b|mxevtp4HS4l5sNpdB+T$q$l3!2+p z9((L%foXFkBrt#i7Qlc7h~W*?VzWuyJXp}sm?i0zNsHO&WJ43V$TInh?JA++jdZ8W zcz#xAO=18QVBiBF0Ko@3U;zb?Aa%Y{kOse&F{rRsv?YEClpT^?j;O(=M`B_dM#yP_ zMOY*Upung}ee4ggfB^#lVtd5gU|I(ia=*;adRa2!z)JccadZSC#xTIo5aG&&8N{7| z{i$+3ga8&W_Oacq0R@mwrD^)2du>Ez`6~G#KxXe$Jd!g;9dRS)9+>~O0ic3*yW8Cr zAi(R0Rk~-Ngv_-raFEbE5ip~#&Bc4rWe+U9t(D+iTU?2nNGXoqDfeK(?10B!+1}Og!0S7Dq0eCNntY>{K zsI>iJseg#v*UVNh@?G`jO7TQUFoA@t90M#@_W@GS00>OL0+5&d1f(E^%V(aA8y897 zgKA`v7#5BCuKLnVvU$!|eEI_0>_iUmdavt%2FN>?pgjd(04Z34+}pk0`@P^BJ_4+| z&=ZLP3%k;~4}4pRjB5$wJHC(Ezkw+|gIE9nOt}t#00HPIf*=6z13&R2KNgrg2xx%x zLkQ=qCH9+$L(9MVC_KYszJ_o#7ppfAgckR6hy}0!4oEl_Z~*mlpTaXh+rvHG<2~O4 zzCZ(m2vo11YA=9+3aN96`8uA3DME9pz?L8Y2ABX0uz>$HSbzh#z?fjc?+ZT`(16H` z!3mf_1vr2w)Ih46hz^9P4@|z(JBh4nv_O0anKMHuX+)DCfJ|sL$lP2y6kT5hn z`rEe&e27?-HiRI70ziOhq(TO~!Uycci6KUjFh>6|Ttr4Z$c8XEiZio-G!*4Sz2MQt zwV=6zU_k}2MHrmCHPFQr^d6UcyHO#+4LQY-ERVtCAs<``#e0cR>^GWVNCaSjHGoJ> z#KLQwv{!>2(CflN%*jIGM}#1|r~}A{_{9q1NQb~Bm1IeH zNvSLpk7Nn6oQUcxyKqd18yqH+Aj*f##0HE26<~v<^cS3rzn&C{p9D&LoQQ;MOY;c2 zA&b5lqZ5dmiLac1HMqs{6U&CHxu>&8RK&`x)X0WlM#gLq(i}5=Bt8A3Hdu2ug3!y` zqkt;x%Zc2=fp|-W+=;oQ%b^^A0Z_G|EKUFOxJ!mY$8`3;Uh`4MBv}B0|O$ZB> zP8L`K&HO61YzYMzP$P{1C0)|UxYGaS^vsK7(NJkngy2v^^U(JEMwuW10uX~0h)oR8 z(G8GD9!=AN2+o~jKLlVrBTcyvfB-e^jZ!p;oiwkUT1BYTlUW4AgXz+ijK@CI&?uEs zmM{PeSX83hfE0Mt-9W=Klfy?T$>*?^2$fKg&{K!>Q$Y2-HIRZqEu57Y02MG*qWb^~ z&`?!13p#xW+!WFtWUhIG8sj{ONL`6Zod^Lq00m%!3AoVd%+N)%F$E|=VO2N*JXXp0 zQKqX>Qk2o308xh+NHHwPgg8yq6bm-3N=LEPhs@Cq2-FHt${t0CEhPvDFjIF+f^r}^RB@UKeT_{c*gby**eyJOB5k}n(1w+*yANOhm@Nx< z^+|ah%_&8QAYF-jO^7T-#3xM%h~>bkHHc-k+JW#`u*^*CBf2C=0+v16LV&#_ZQ8LI zNiBs_gXr4Tiq?Y&+vJ=!RjD>F+6zhQSqt#GR%nG#h=f)shfw$e#!UjEi-38A+oRLX z8nw}T)Y(#DR{&^IC;gD9JqU>fQb;2Kx>LCyAO>wHhjQ=-f6xYIUGPijIGtKBf2lBgF=V|Vkie)&;?>(hE^cD3b5TV z<(=fK+=ocS$)VX&K~7=Fg;i*TIUoZdK!|EBEbgrg-Ypm*e)`&i2vQ+12L^6n2Cjx?5C&Ngg+`bKA#k-}X-$(L(#A^y zU0?>st-BNK->2N9sO(SHG+wwl2{LeC7k*&|=7tC+U-L!Z+ocH=B}t(>S+Dy7VjzYP z_Bst%020R7n&gbV<6E5VB9jON7=B_XZs2MVhBnh&0UqECyuSGbfh0IwmaRJrFn}Vq zl~rRkFZ{xLlh6N&5QQjiV;F9RdL^yZG>HWuQLp=fFZMblt=%y;iGlS+IX#F6wISej z2;n`597e3G~+WiiA2rhBV_m24HsMKv>ad1)BMc0A$91hGpg|mJ_5SW2M7f6I?E@=Jkbj%h$FVT{&ZkepB> z7KuiHVsvN+ba3Hw_~|Ex@A|Po`_S9?01NVcyNcUj$&bEv6(&y7=28* z{%rqwkqHG*feD}h%bWqpZ0l}%Ycv*#U&iWoaEEtz2X^pkC~kyY9vk>rY=ju<&*sMg zhyV@9J`C98O44BL=8v))N7ls1%HEHLhH~k)PmmmRo_Bs}*Xp%1JCDs=N#tBGUU?^sA z24;sS4gymOZMin;gGgiZt4XA5bOe&L{I)(B}|hXCc7 zjqx)HL|`@242PHWp3!El)Cd;|C;sslu7+{GN$u2WB>z^IAOH$5(*I_pBp${s->3hR zU}GzHVXzjxS#2E^ZwT-0@`?E4f*@5RN5NYOYtD6Z$Y!79XiBei01ePziax1>AOLhg7jlt6_6bmS3RnXb z;KU5(@|c))WmS_Pka&uhg^OqJAQxLR$3R$B`p~2a0$9oOI{*@ZX$pLD0HDL8ba|L} z_g7Eoju%*NZ+HNZx%3Td*2ZBX_e8fJ32y&%-In%&h!?BJdZnbug1BPBgm5lI=QraM zqPLfY_ibGE#aNg14+rs+phH~kR~G1d%cF#*h6#SI^U+6b!Vi$t-zERNFH4JUe1}kI zMSi(x_RrcAZVUL?9SuyXZ*6e&TWDojwpK!Je)Br(!#SgJ?UhKF8?9FPKn1r8v#e(0c~f(ismS$eq{6@ZdS zXV-Me2v{8GkT>JFw)U|rjtljcQ0Rt5iDqz^)6$6C`4i^6)AfV8q+_QDpf+`{s z!GsMTwsP(aLIZ>XEaSvkdqoi3)T&pr_UHw5(;{lurlM^5tjx8fDdyY>VS)vq8(0uE zigfJhvnSh5{^&r%X3x^MYEY0;&&;znTXXO3{cW1kO(m{nDjDiomwNer9AE&jV8Vtq zuwbE>vE!6VCYEpB5khp+3HU(+kBM~16}qwa9fJ)z_|aZbm9ms9T_*_hy1;#jzkwDJnPHS+zw~Xh}#i zz=jm^F?rvUA@#V?04iYl=X4!75K@qmA^Iw;O?q*i~{p-m(uzes_g9)+u?%TZ@LZq5S#N?EszDkvdru~}VlMRG;}V-iZ&QBEPz zisn(nx8+=q?|lf<$43U+!6Gi)YRBOU!E5xPbXf2ao^h*v z4)o6HMuLFfOkfQvSR1&K*Eaydq+I%YUe;K0JV$AeHxs~@E|`%77=3^OA30d19w@`s zqz@z{m;iJ-^MMEmz+1x`P5od3FuTPtZ*0MpMgWwhFNkl2FXF(eJOViU&9I7ap;$;r zfPvV7fCZ6D3I9@pM3{swXZK5q%zhO@n0#v^3eZ57lF*8z!3YBg_z2ZR_c|-`ktH5% z&)8sO0hEm-cs^XuT88MyJ(i?&=+c`-NI(HDa>j8l`hW_Q#S!Y!&3b+OWJwhHkt=1X z0}X(Q=TfQ4RsI8dFd1Xtf>@He!36({AM6MMiUzF&9snf%yBP;TDNK;~?IQ#TWR?br z#{9t~f-ni=bxKH*GWzk1Fk#?-b~&97Fo2L686on9DNd2B?jr}V0IFEf%aZ)@A*@^_ zp&%*3AC}}%;__rInYj@XR6v`aiGVjX^1fSDZkz_K2rQe$0#sEeCA4ITEn!l_V5Kg4 z1uaQ2|7J~6QNW*DnSdre;!F`%^q?kv2sAfxfQA0)0~K&U3J&l^k5Drtp4(_iuxYL} zlBA8QlV(ctXv_%Q3tBtu;h=1D(xpPgkRTZVOS7bb2t>dq8tA|VFi@gAQN*5HTMG;k zb{1EPk)A-r2?H!p)Jw7;1p)uvNJLrUNTwQeq8*t4B{>s;nXXGo^MRL>2;hf{PE(c+ z#pzP?*~qn|v?S%U;Q>^D0S=t%0~)Y^1CTnB(UFd>o&|tTKVpEqg5U#pj1vMD;DD-P z06HAdDzdmrPN0%Rs2ybFNaiXMrykN`3UI&@mN0<`K)?YC2&qU!2~pgBR+wQGiHl4I z6HpZ3XYmmlVDYmN=}phDv&1J!;#v~Bf>E9%5yTb-Ab_`qB%>^uVsi}&UmH3gb{_y~ zGcD4a)mjy+u;tiT8tajF61c$ss3}P}D-seID74Mw=}3I~(?kX{zQeR_78Otd&2+^p z3_xyft72Whdc_D$!Vmv@I|5FccvX2M89-`RTLBADU;=D70EkmU-rbtFB;0+Ng-^=K z1sfm*Qdoit6p-QN>^hQ9#Jq$9BjH!KU;<)?dhQ%OWQ10n4JQ1 z^-r+6v1C=G+aKYrMH;YHe`3Jb4iUz>BR*_dxCXqdX6{IKTyGg_9C*$i$*s?NPj!tr z+n_qYC5p%q1B~0BEu85>nj!I-Q(6=>^)5-~yUdLbQ@kOTbB)l{?~b_I0??Tt=n>LGcJpRud${7}T}4?%#_ zrNaW`a%1Wg#eyU7ttLh14k5q^|MUeq4#-~( z0fOCUE`Fz94XBAW6fQHc8&vA_TgnM3c_ z&5e(AJS5S6<>!lUxrB~{@84C&J&a(>#F^9e&9GJ62plC+Q0%dL?eWsx;2AG zz}Ze|i0Y}I<$N22q#rS5T}Z$i8qHrvAY4gE7)11wfYd=Ngo5{I12O1J68K+dm{LOk z8vzcRFudFHF<(3}U=@*7Peq?dpqdc*o#4G7`Hj`{0l)xBM*-Om5$cXEgn|ij#VIjF zE~x*TIdD(WI~eqPkVXPX43t{3P)RU;Eu- z#Z5}{#GoyD1PMd{X=TXxA`T5v0-W;`6%Uot9t@NZp zuAw%400d~(LZI7Q23reu#C~WbWJcz_-6g?H=79)iM=&MmkqazdBB+4`0yzJrKTQAz z;o)Ki8^xhWLB3FAvXU24=BvCWN6?^;1tcq~WJri)N@!t7$mT-Oo<~i9_dSHnoo3DP zWnTskY)TDp!XVHsRnQa8`k*GQR9zbr5ix&TkX8ucyZp3|N zqr#kId~U=*mP8pWC;&jg95jL`VwcG^eJhoX(>m{qK^3>Zd7SUfaF5B zSx3m}ocg1xX3LpYM4Ia5;hDyyYQ%Le7R?|MFzFea{OYw-D)U|HH=(FTG$}|7fg&)% z5G)xuLMTPFr$xMHN_gcBZmLE&XcmGiw6cb*W*k|TB}@px8GQeOD%@)#zyT9@D@X9E zvI&WuUYUiiOuNR4HEIi;dgijGgcW=OFFY*7@`5RJL9Rq<+Z}5~Nb4g;MW$*hB^KzfyR|QO41S>_bD#+QYmF6kPdIzq?DXhX(!bT`d2!X?@ z?8-8MwA~EO_AAC(M6zz-b3$j%B1%wBlf_mMW`!CyemhLKq7E0(Za&l&TOh`gn{l|((Y={Rz!35rb(*pm<+2( zxM@lz=SU2JDcG&b-h$C8Yha$m)TYFa66Ld=hvANijgJ4FwO*^+QiRBI1QR?iU3e00JCzffWn^FN&2Bo#dld zL^P7#(o#gz(yn(5u1EzexHKn*^7DSSdA;K3PK0TY;L zLtL#Qifh50EvAObO9r{0sOKK*-|f#n5t0{iv2UR;Fatj=@pf%pP~DctM%rtkW;@B7AS^gjQD^*X0Wa4!Z!ZVIpPb!e~iR_zNn z>xGub&sxOiazq!v0_5Jp89cDZ0zd>$a0Qnz25a!}7Vq(bjuk(I{9^4x@5A0g zB3J=@!tND+2e!IK9Lq7uszg&*0T|!y7)MX^kw6dsaQUjj5UVfyT7etL!N`FXosz%; z<8j2A0w3Qf?(!`a|1tV?muUp9;BGNQaPlXduPT^AB1|qtk;EBOaQVW*8gH;0v+&{? zD@X`ICwp?l!U8Q%s{)#GgEVT2mNG^gI8BK#`|$MbjevqK;*$T@RO{Ov{@>@}8cwstf5nr{YEvJty8H{PQV z0Ky4F?l25P>cYYqOiL191pPwv*Ksah;4ej#vmgiXEz!g%Sb+}*^e(q?`(E=m*`^hs zu1Y(DGXQTQkaR`lvkdPuP3yDDP3f)Fb5~)sM)+&ovNA>3RS$Q8H=8f|inKUSbWfr* z@D2kwWCKe>t}2AGA#$}vXmnK*?9PC7$u4a63Z0t7bVFn;Tkuc=0xJ~tk|{Oh zIs-g7LtI1dOIzK?=Jjfn?zB*~Q<(p3Z%xlVJA_onDrb*19I(PSpLG#;!4WS+N~`Qj zue39iLsJ7UAV4)l9CZ8HHD=>t#HjKr&+h(=vPCE^a%Qm>KO_?zwi;)!W2gQ%knpegbZz6i(-~MfY|y>*ydm#2jnOOowYWKSbCw-62B=AREDM8BaRikQFI|^@CgjX|!6{xgqX9I0BwRPJqEc9Sq z0(fdrbQpejLp<+O&A=bbzyl;e-ZCv;L&SNjwdH#FhYw{Jyf)VkLv*urZ1;CZ5VlCA zw}x{uk1xb}i!Do#zzkf#3ylAO2*AJ#cz^^znhW}>>vF7CchxRJcr?w0{{s~fD4Gg2&8$Mi@*z9Kxu{~a8tw*bHtZ71cxW?Gv4r(!?pJ|^sWl_ zV5fMOORu0a#ENq_Oh~|yt2v{O01RA!lS8Vr?#!VJ8e0T8nRo9}*LF)+HhsP~LlE$w zPatRO_yuNj0i1cGH+l#>Ks~j$XvaBxKQugV#2Lu=LPP8)(Dlux@~E@LXluj_i-bh4 z0Gh9QqkBN47q^Qq1c-kGUdwQyJH-46!E@*O!@|LKJH+Ku?XLqiaw}&_v;eZNIt;vd z@OAgHz`C=8I$8kwU|av-tz$boAM-{CxInV|w=V>NV;xVE1PLs9xifkK%m{HK)R;2_ z@8XfHL&Th$v8L0zr%TSkQ-pEvdq-USCM`HbG`L0-fWQwtl1o7AYU7N`UO z`$AaxLf^tCoHzhfI+#~H%`-%pt60J}M86A82K0QIyMT!ozzj&h3S@u>xWEg*KnS=% z&|iQAl(+!Zb{InbT)|*QW3oJ`WKnV1_2zY=- z3_t=rfCOBC2ekiy3xt4@FZs|H{m~<=O;>J86u<*`01PC#2(*5ZyFdmM{6`D{TLbSc zm;xM-F?DY4;@5No-84)TfCn6Vxx0X?FBlkzf!edZ+rz!wdjQ?r{dsaUHkSkmq&^Ht zz6Z?atW z9{d`1Y}vDE*ItnDHZDV)ijx8*AtCs1{UK)j)EspZB^=|5x&jS6P%;9YN~1Bw=2FbA z%zAL_5CJnvZM6$LcrCWsJP?QtF>X7mGN5L7LBA9|Y9YRp{&NbH2^BL9!5VG6F)-$o ziX;Cq#d1@Ox5v0s3^}6C6DtE3%tA{o58Q(fDC>S2AOjUugkc4pwA=2n@NoPR%rFn~ z(kb#Bo9{Zh>S{`{7mW(=APgnYkVDyM8>k?P6x`_n6jKZ%j1*b4=|KqHJgO8K#axup z=@N~q!U219szl3rYm-PtAv!X>CE0WGy#)TyQ77R3q(zbxLon{7AA!6ysv#Sll~yjJ zDsnthkCO5_-F9PBDOrJ%lTH_4u=7JaM|8*q6~j=578NhB3C%PeW2)9{wJi$Us1AM8 zLZ|jzutCezJSxIAc>oK^4cBY($pi}M=ud4@P0@p8AwtZtN}alF+kgco6jr0s&2;}p zU3Z<7QeTe(7*mRf-O$+K!jJ?|Ny@=kP<rGm5-K=Gn7Q?Y7~ zs?Vt{cPd~wZOYMxXMdoTgyX(m@Yo?Z6&qJ622WnPWTi(w_b34f$i%TnXAD%4^DzOVj?p?p8XmNKWclS0w5jw`gOR0^`cze&FiBsCwzTI zpK>@AA z7ZGIXBzB9+{%Y1g8(uLxRvgOzc4C7b+7F0C0a4B%CIdXm z2WKWjEZz}>b`;78gOb57LN9+qNuE-cw>2UbrBEWo;X^LKL^qBA1`q$xN%6QRM5Fi% zkC_~zrHB#$Fa8mAH;_RLXn=wfl%Rt;Nuu@+M-(Y4?o~wj-XleFfxubheY0yN;>xH= zUkW90MPVRN<_F5t<-n9Epg{~|U;`ZBK$JBg1FY%oe1&|nX! z6dr}z8N^PWpa#vn0S-!cgBYN|nn5wApkNbw+8oLliHQOmlum;Kl>z?^e7chXtl$NXw2B9^ z@{=^Gu}eZd=~f$J!K26#C>Z==4r-9fq11;2{ahwM1xiqZno^+<;o}hj)XH_heYwi7IF&|IvOQ}N|`Hg zAG=nY7jMcz)>ApxjCf_qqlpc*b@%_Yh(Da=(G z6Q#GYa*S7J_s)}imZts1sVK2P-vA49zzre6Jz1Po*zN?w6&a-Rd~C=Xv$vi|zLo<8 zH`3Bj);Hkf0vG-nVz*Y8#MC+@MM~h(CTmciL5VU&G`!)EJ^0GMeB~wAj7SvA`7y*5 zpss)%+9B(-w3`hkMNoj?KUTpIhT!XyPmH3{SA~(lP1fEtdtyPUot% z%x$Hvk>gsC7_hbq#VAG<#u@{lFxFtCE{bG{2j>4yYqG&c!7n}gJQQ48FVJ4zNujY2 zQD^3Wv^=fmK?2}rP*y=2ub}l8%lZ=&`#Cd#*7UFODCnW2bYVW)EgJtE6im0xWglLv znFadAD%=~=*#@NyO7N5Oo^{bgYcRY!>0Z)`ZR~dcq`(FLWy-tE(4*m*vn3abg?FtJ0bCq<8JC7M%Ha=x zlmi^u-gfl*&0r4yWY4e!Qp8nm!yFG~3TTjeFM@!?aRY^@PFb`t10EDhLnHt=M;*Qm z@d|&u0_|vbatQ<=fB=+tOuokY!Wkawhd2LSf};LO5G)alYup3y->?N5ytQMw2W8ko z$ud!nO%VZH_K$`r2d(j~K^(Nb1SK%R=1q|Kw!hslbtX!%9o#RO<6VLg*2xrX@eRPg z{vPCrh9yv&T1Xu|N-+0!*Bc^$6&v#v;23%jWw5CL1fcE7XFDa1PXf5ZTRC(GX2Vf0 z!L6T!_2hv4_M_2`(Te8f?*2e;_h~Wgp#hPzO;*dd%zecB1hv%&~^>j(ANc zEJ6E{5cU+%p{8gHIZy_n%=TUD&F> z@ConGs-$oy_^<>%NeB5YC_YW`4DlzRkSN?s503{EGXf3%5ca+y8m@sHt|1zN!4^=# z68ZoQm{7_NPoAVNC>9Tq8qg*l@FYwC@)GO@77V3aQ71<3ZXBZnGtqd4F(anH06ozb z5F!ZBpbsp;7J?xeqTw4rF&Y0%F%{835CK5+MvoAyqXKv0+jJrbqOK26!4}f77y4id zSWzc%k;Pn#7i&8cs1A-BBot zP>f*FyeP3Dnh_O(LHo!-BQ>%VEx{pA!uRB`e)?)2ZG!)b#ur6SBK>U*^U-8v(I(I! z8vc+RmXRo$u@|6G8mZA5u~8MbF(br~q*C%1!x15-02QL449)NwJQ65Opav+ahx!Ty z^sgdLvLU+B8}G~|tV z5%9iL(iXB2C>i4Ef`uGs5<9aK4d?DL&Mzn| z@dpjl4axI(rgKcL&Ogo15Yh4=o0Akx5jyh#6ShnzP+>n;kQ|({f{3yx%?~*V=2{Tc zKyAbpakDxD!$bcw0vLnhJr7b8<&!>5&L*Z{DKm63)w3eZa}c8<=`QIzZ2|~ORABD& z(#8|U$jCv}k}V~)As6WGf&fE3F(3B96F2myAjAI_GiE4KCj^v80|rb{jzDvWG>?Yv zUNjnc(ldQhGywo6tuq-s5g+)WAMn8wlR-xx;zS82MJH)RS(H87Gfe45^=2+SO%jRz z)aYE)93M0xuOS)Saupxq2%Jd`<(;^hp zMK!?^(lQuAQAYc~7H$;wG&LXkfgd#03|p`VYqJ(rRRqtpl1P%tAF`EK^C2Jb!B?{r6~r+_MRYXZka)fkS;GX~Txn1%VjOWSQCAg7 zE#fW@kRRm1=kQe?c$FXa;ag!ZTy?@!0q$4waK{uhT^Yqyf5I^*kv^RDS&20$ZK7VU zHCy-LUi(2~H8vlT5Eb^cA(T}M&1FQtFk!Pr2s~jIV&N2ifee5^dji!WT9nU(Fd46_dy=^fm^xN3_0{9)>WnKFpCWKWN8HmJOLZTAsyxcYNx>yU<6@zBI|a=OKoBw z2h=7k;UD+GA3F9QS<@yKHWF8oTC(;e#uO-SGihxE3U=XXp_Xo;_85c!QA~|{&{ijy zH7NhO&>_$OR}YY9#g-;PcK;Za!DMz{+La;>l}6u|QH0eh1SAsu!BW-pOM4?-&? z5M49kM_(`|_0tS7_Fq@<8fFkOc$8s7*CGb?R3(>D?w}hk*K)f-5egG&ox*GxmT%Mc zF?H4qz4ae!awmoqHx*+`?<;s;Xk2MmGK63kaQAX|0dF0yWEbjcBt<7K6-T+RQ!Bz4 z3GP-D7o}jgB1Ttw4}=V!!FnzC8Oi{{qIa=w_A2Mq26y6C!#6dTP#jS;Reehc$K!e1 z7c%Yu8{)TavEdGw%kGvg+>90b=G1@hAsEKDBK-DmAy%$B7XWf|^cWX`qk;?;n1TPH zRveBY7Chk&$^Z)F$#EfqgSpUyDFRxB;&UGY4a71-lR<+kf@YPji14=}SanCMwuB=C z2yQop=K&i|;S^$F7oMSMvEdn5_!Jc34wztb8-i#d*l1(vD4>7|Vi*AU5PbKu`w-V5 z8rET-COagySeN)ls`rUC*CC*w4DP@asQ4JBp&Pnk8jfLQU3eDg*MPe;f{CIGrg#^Q z;TW>`814X#OEWUDGlL(Jg!N>G8={7}(1<_Sj&bA;<~DxQ;emAm2$QOccfxfeQGNd(LUw`T zT?MX`Z$t=Ufq^ski-m$a_}GsDS&#|YkX!hLFBu}D*=na5BC6RTm>?FMHicLC4zl+# z?b2HF@*5Vi9fMGBd+bc?w<6d!n0gDZJi|^oNLl}J% zGnaKaczqdupO|jD;S|34F$*#p(~&sc_*p@i8#lTldXobCMSu@FDpGbD<~AKDIu`Ib za)Uw$`uL9{xtzPFmtPA>v zahQ%F0)(4)D?VAQ-3dg6(T;+8oQZmn3;B@Kc_~0xg!lLuP?@jkRvcDYhJA#f$v3O_ zPk+yKvA-mYgMxjB;+i1>qG36%XL*wAdaA*BCr*L0JDYBwp`lOWYU3ub7l^GNLV4XS zpi{d>em9Q3dV`1CA%uVoJmD9}d9sh%vUS335kd%1n1Sgbh0|eoI}}a-bF>`-aEBs? zB~H0-B(qi2d)2TZVq2nVo36Q-41D?^%9k+i;EC%&AHbV|pW!%QI;P$EofR7)URx+W z^+?;>M({c-l{k(NydmHj0Hiyz1NpiS*%M~rw;v**zuO+*LBRjxR~!^sJeilmo0~x! zc}*a^Mz*^^nYW`ELS!p~zR!9Z?7Oby>a)z0o9-QuhaMC9wXXyLdvt$>gHWKx_W47ogpyXJLgy@gutm8IN;0OdO`annA^qA zthgN>0zd%rBVY1AfCE^d0+v7u761VV;9+(iAv#yqbL1z0pws={Zjm{F$(Uu7 z0^&nn>(d@6CP4CMpY~_J?cYA`=iVxLqVbIz?=Pa-FJ906{uw-8c&)`kz2)$`>c(-r z=poz!YG3-NU-BUU093&8CqM->pYuW4>=^>>rPE}0f_l5Yn~R_5o&3qm^;Xv0B8DFJ z9YO=BpZ;sV0RVskr2qEeUJ3w0jDZ0F3K~3!Frh*(f)qM@h_J{ch!i2FstD0jw|N{p zdh{sn7!!;N1zjPDGEN+nEUz?VNwEkhm?Zx%(yTa1$<3WSd;0tdG$_IjAc`72iZrQG z1pqK8eOmMb2No43s91o2z|Ax(g#x&8$ZNqKGkcQRh3(@k2KgbN$q2{mzI0{}KCeth(U1_S^WG*B?`p`J8iz2FtAWTH*Fz`k#^EfKVO@!TZ65v&JUC$jkc$^3_`!H_$}A#Jt$H=wCSD6%IeX{F?`qKmGuKgnh_bITV+S0R<6U zb^t*;%~jW3b?N1vUt$IJ*C9FywORjNo-HWad>U@ZVP*Rz#sL7teVAB5$&qN(b5;>V z00|V)W*cr^=_V9!VvT&=RX|i<_%7fLGs6Vo4BdisD4|Hp(A`K&H;AN^=+HxVheNjv z3WAh?NF&{ifFPi>V$I?AKj&PWo3rls&0agcz4m&)=L-$*F5EHg@uQ%qM==T%SNR}b z{*S}}jJcZnIY_uV!&oU4FOLE7>)FWf%tl#-%Mn9ptsQ4~*n+5nqj07O$|0wGD`jBz z#_xv!0Mffvehq!C#2U#bd)q`pj73s1;~%J-nnb+| z>|EA(K_wm83uX4y$X+s$wmk(c7ClLz8;lP}69MEN`3{88+O6!Hq~SGamw1@G8+YD* z^?-}j5z*|tH8L*B<@K*`%Q<#(oIP5c*3a}~s&#Jz7|5~$0DzaxH#TdSsPEYsG$UF` zvPe|;E%Y)BcuO0C9QSCFQojv88O|xH%DHci?zgmyieyx0DSvRSc;)v>5dkW%^2*YF zYx{e)MZb1m+M-l8g&7=@kXJ!4$?nn+EeeS zvu7`KTmLLFUBcVt->zFtqxRS9K}a9wq8SeSI^;zLgD;O4t4%4#RBk;L(A(krX0Pr7 zVt5zVte~|x6|K>s4>@n=?}dLD7FG`hMRn@=r$29b`Hakg_E+X5g$sR5ea%BYua)jJ zJ*ZRP4LSc5Pq_-e|8GaOYJ_xpZOOWnpvpdznRhm{#O_j(QcV9QmX z`djNuxx&MKoUXaBdrZdg}BN9*%RC(=6S3j)dExD;~ZY zv1cimjT6@)P0~oE0sLBO5+81-%I#0?zk+dt{%r?MP>s;>z(@0u%5mC@w9B4@b>y_+ z=Dl}w4B9@*4)|*XVze}h0KG2h)OgNE;9;S#G;T4oah|_t)*LUU#%yZRIhXAc>}{g( zV@D~WZ_*z%>&yxdDk;#ViDHdM5a2NQ6-Qeql}N-QP?AoX3;SFhn`>M zjUn!gtk&DeKyqWg)^*6^xd8*zJ-#c&QUl5#kjug}BfT&tmEo&&f`}-FHGNGNnX5K| zPpNcBq<_gzZ$$N2Gcr2_(KM)XU$5D&T6L)46B~!Y#}sM~D zdf2J!0T5v{gbELkM!PagDW~fO^?t4a5Ai5;omJm(P+`C4O8wgwTqpM~W&K|k$16li zafeTpdqW74h#8GAz+NBSZAvJ|X*_)CJNwqbQJ+NP=TvAVKc&>s@g+7D11>*wkc z5mQSCV*<6XBXy}TyFsGbRyMv0>{G)H;Cpy>=STTWViQQCq(*|>a&M+z5arNI(;Ce9 zkz>-ob~~aQS==O9N0enY%e)FZY0F!jb>S*X4<1u-gsl!u0UhRZaZh>5Zr}Dx@7SVT z-_8a}011xFR-b#~9_vI=t~@0zcehijwfrMuX+WxT@Qt%i&TM;cqR#F?>GU{MB!if8 zl$fuS*Y|YW@XO!`&%`6bMFTfCOIoF~b*>Il6`6>Eo#?hIQx}s|wJ?g$Lf;Ge8x5J{m4n z=`24o|G@8N!dU2*B~HQu;*NdW$2XYP`kUVRGk3sO>Q`rlf7-t#tgAC4UQpHi;M|0u zLPq2^rs8Z0dE#S+vU7KvM3QL_nZ*4+>yB64h-f`p<^HQf-MI&&`O6(JAbqe}6gYEW z^#CpY%(?D)x=}6T%FEr@naVrCqM#Q)Mq|dmRJL5k^W5Bg^`disGImKx`Nc%bldc~` z^IPcgs^7vQ=fzQ?0p0_9zZdP#_lvvIKmS%b9VU$I(tNkR^Z4c8+^_PCU?N1d9wKG~ z@~y=`{7cXqRjL|sf=8TD=slv4#uy>Q;ENm|SU*6{&`QQ+N}9ss_nRkxWRSA+OW>^* zsxSRdD0f_GszhbcREkq~|GXSOIoc3Abb zo;nZOrVA8sk-FZ~Q*##es|4J-LF#J58mR=-8bf7~}#r0;69v+kn3bGM1D5 z*=;|EUthRda|B;cf|P*-I0`x_OeK4qsDXsGP6S1`kj-Ec1_5>rfZTjA(fTA#yvIA# zm~Lv2s@Wu2p@c4-4HoRhWaS0XNQs7vzz2~+R(hoId&posS+E}11VHp7XW!ix#u>Xfh$ z7-AWpU>)me^6v3HbyRwlN240$eq{!WPXdb}_?nVIc+-J%Nl4&HJzq$fh9a{~N$*r6 z>Glxm8>BNp@`u)>6_@z3r+)kr*-B~Gj#h%p0#z5DJmFp3S5rhfIvF|%vO*iC+mPQM z46=d)>1gsseej@54jhFR&B-Ql_Kvt8dJh#jXOdgpLf)K0a%Yot4wpsJ7#+|UpYV=s zraQV$EFZp!sN;h*PtXi3q{E14W4g2Nnv#Zl6}UL%**LI!n4xxmy4VP?mY|qZ9*6c=uZ!HG z<6^L-K6clMJVAlBPQrZTxCqEY;Jjd94$ey7dsa4Me;vd0{LW*)L>_7i<#_XaHm*6Eqrb zrBEV-h0jaeM!ZptouCw-g$641suXrFX$}`Vh>sbrxW1Z1tZd3?_NjisfxsmyenzHh zT%JrAsW1!($B=1DQM9t*0)9Sg?kja|6WWu27rRzC?IF6okghH0C&d^hXXads<`gBP$H)2tYOnBY(wK0pOtFi1hLeQVsqpG;iL6 z)VvRHvIK=BaqnUi4A~}IL)US2fLh&5o1u+JO_vu;j}i4sn04K}0a6SGU02$Rpx<$% zjxfL#Ns)*E9+@Lw0pxzgwLjGIb<84v#5E)aWMkcs-AM=fWOb{bBg{}aWNa_VnI3-3nfk}XoQ84a&naab3;bvytHG?y4LRcaW&z1 zGWvMrwV|IrPAMJrLsNj+6z+H}Au>hurD*NdbWplKd*lFtTM~iqAIW)!jH* zFW8_S(qf<7f4Lr*Xm+Y937VKmGap%=O1@Xs}0#4lENd7Y~w1J@FP%ZLef&wJ=>UzFZmYXU7=#CstI> zjP&Im(!}fatYoI)yM*ERE}4hmHdBP`i1^IJy=LKZv@vPE6r966<&8S+;x8^?$?AyU z^oTaH6%E=6+*^;|gm?S3-F&6sH9dsRRpK0`gI*tzzfiy%gzFZ5&#PbjY)`ZG`q_&~ zg|Nev|~Qv1*J+}ELizUnc37U&qs-i#bLR_uGTAwaW5EBz`^wgVdu7d)DWxgI{Ch&9+ zY1YI9O-T*aDYn+RrDx}GoVldsACh9ZZ8$=DI6D~i^y@2<*cAEVNXXAb94TTZrHZ5) zSrOMysGIy52(dzsgWWrzsB6g^(w$O&8UHap!K>dUiy;9QU4WbsrXYSy-Z_$1mp92& zKYf~tA7O*R-evaVhv)cfOumw@+2A;&U1CV_=R;J>zh1OU)QsRMHan(GLiwyx5;R~0 zvJZ?!S|QxtdI+m-nwx(U+sUZH*`jewQIS9KrsVS&5Upk$Y10Um<)Vmd3c|S4Sx!wH zqh@GgLr!3tj~bJD)`43$MRa%1_t3Wna3qWd`iJ;J*xVPgI}KftErMpGJ!TD}VXqTw zpmnY1YnMbyZ&o(eR_xxddZ{`i{`39w&*As~PN2>wS% z(f?mU3dRVKqW<%vnE3w>9>v202r2{j3;-D`K+z4*)B-f00)`QQX*^()1K8UA2Sx>l z0AZv514b?Xr$yzT10@8Yq7r!B1a!RzM#g~eC;zcgU@{^YFA=FY5rrBNl?@R!H4zgt zk+>w0ODWOg+W+vV)Xzj&heTW3#0(+Ctkvu$tkL# zokY>e9P&nz3jXPee+k!Wl!}bJN&%0mww`KOsT!r4nzD^LKcHU9tHE+tlPOH|dUO)B z#F?}ew6*I6^dCJkydJ&;Lq9*m);q>*>Bh#ECbT9dnkN4nk}|ilx%Q(hu$q=)z$0yk zN8|UbTurQkBdlE>+cqiK&fmA=thW10u-DSI?d<}g41P1&Rfonx7fHfdkEjidl=RZhlobc=)AyjA%a}7!5{HI98u*YCU_pcSH zL`kPaeWLXA|52po30d9`a=3GH{}HYssR9+ke~^?Vaj`z3tgNh(zp~bja1BY-trHql zLhw&{-#7!;n$+7kLW@w#H6+!o72W%ZaIHvv+#?L!9T@T>y0)ao4O1s;2s1M?3-=cm zLW%xkq%H|-W(C{Z+dC74U8&vOD5Ar|!|&FW$F6m!&sxq?de2`DpI==5XrBA|;ODQ= zt>4QBe|CQTJ3A$y2?SdLA^3m%s9Xv{r3j&xKxlhJ7$6Xa!U^kd{=bA2r;A&Of}xZk zKR8qWv%I>z%&iPRrR^R?E^P`KC1tK2w3#Js6O~~_p@=B-t!w(5%JG-z2m}|l###9# zeTdIFoZmq=O;Z2T;fl&hC-1?NU!zk#Rr3ut9}qL%Mo#)Koqf3^NRM>bfxb@gQKANN~`XiyYAfdN|c*DvZPFZ zbB*gK-`-)83$3H9u^b5$A1V5KfpyL;3?(7DZFug|^nSL)NygH_a_~X`~=ZB=AplBN~+Cjng9W%*1JtivC=S z;2sND)$Q_EHMe8#r~j-Y8Pqx(!a;j(yUM9hwcD=T!KRDb4mx_noaMUr&11_|%{{NulUsxM zrczKv`#g`ct21^Vy0^_#TOVD1RNHw) ze!Qr8ji$-cVtSdVdcc0|3qHaZgNmS!P6oK5=o*7`4{rXi)fEPkm1_QZu!BZh785In zH%t5mjv4-W0#&jsalDz`aTzt?A8s8S1twiNtksRyfFJ9$#@*X%dSE6nRTUTa^QZ$| zpP3iU$k*=Svy-QEpwJ|&c)fZ%(Tm_q{!<*ys3UQ!-)ic$dsRb;L7hRtxznND3lBbJ zEBC)~oC1oY1@@;yyp_yJ_m{Ld@OL2T;m0?XBr;y%P$B30>1}!7hJG}MS+VU;9ZpvJ zoB3tm6{gD$&!_eB>!KA2OFMNc;|YCz; z$EQK$eEejPr{T}(sQC9kXA`PIf6r%3p8UNSlKatto_!OicRpZrcWYqi59-bSCO{Qxh)0&lR<^~#GdB_%=%f4ZR)sonJ?wy zOZ8tS4@iC;$DqkdP6@n&Xpk&Ec-dg^f^*@+K8rl_zXjZx6gFj%uQB*b2o7D){q~xL zV%bOMBFq*PqHw)857|i1ZA4m&GvRz!hOE+&Y6DVBs9@Z2aZHk0r%KpFu=*d4iz=HW z-hUI}(8i+2TjEGDd_4=u2s+%cK%w@FgEi9<+T|10FDNyBD<8z-wYG=kQyFJo_p&}y z8ziL^9cNx-D>-x6?~t7H!K|1%o_R3H8gdIEr_km6={(9N8sj;m_E7Oa+nD>zH*yI8 znih;zp^!RDM=G%jwb~{*Z#M?5=#kJwt7{dUiw12W?FxGw8&(g-E2gLh#PXq-`zfgf+kXah zmN16fJ!dy(EH}k>_L4n>{iAkyV}<;$6wN(H$_76VT|}m`733+h_0qFxm|!OY$n;nR zGPWgo-|3}`fPh)H(t7|7BwAsZ56UPPejWR9NxQ6+8&$l{xMfhs-GCn={d$TPdALV& zaZ^*)%7L({c?h=4Ne{KM&mE?)z!2Bo53Rdcutn%ioCk(&d<24sFy$(=KzomkQ)U3w z4k7ov>KA8;t-HDQ&bzdd{EMR#pRkTaS~}ViWma)8C660PX2S?+q-#jLjC37k-Qb%j zv%ix`zBqf#>O-jcdRUTwcPR_(;v2vaOkt;H*KD>?CMR=dcCRG7bx`1|Rd#^6l3QP# z!Y^K4NW$_L2Js+Mh_=4>Fh!WmWw*~cyHNUp3`{7w7yhUJvcg$Y8f@1*`r&r8J7Z@a zSUkuY(j9Xhzcu^z)QDJ11VCIpJPfL6ORZ*_-1?So)$j*WS^5uoiXf3t8d~VX?lq542K%fRL#VuQNWt9g+dAyhQA;h-)e! z;w~91OEIjt|?fC4A zqhaN4Z;}$^yP?IO5u|Y)*1!GBiLZ1LJKp}(+?&Up8;rq_HKL0y+{Pj-ibLZ+=P_FN}iicO$mH}Hk zSL-?T-w_c1<>six$*gAJsr1cc&IM-dV0PjbOjl@$?ESt>yMlHS#tyTHY0E8bSGh*~hm#a7SAwLBS@EkosAB7cJ;p_GMI%iW zE6>m@y>b8IM>R9@FD1juDurkDh339M%s)?@snX&lWrNy6qwdp)Foa)Hc(clT$$KAN@3UjZZ-w+M=P6FiC1S*UkMy27neJ3E~xtp zN63vJM@w2S^Iek{%1Ow^*gX3f z8BCJ9q1?rk2rI{(Io@Qny`P_5@GRwp-#~FnnsPo)nKyeN^-cU!H;z(W` z!$cKHn{cFk-DJ}^@=bh#$7elqBGa&_R8sj&vapyPiS)(~5w!a0-+j_4Q`4pPsbnQl zZxq2gcwt4e3{`bf3RKco>n)M1So2(Qk1CX9HOi_w+lC=4bSPbVAL;0tMdm6kcZD<< ziv3k3ZfutQ!XQ@ab2O#*a~crO3pk1`Hz-@lo#D>yDR9IeGI!(=0-iJjbo(~mb7BpnWHbz)P60*2n!VB>wQdbIvNcs4Gr}-&4 zg-D{@UbEZ#U+(^3$QM`0`W##2q>$*$apzE745T4;Y*u)>h&(rYdGxxF?4Yb;B0iC<7JKTFG@vMm?Cr{QqM;%Jy6@>ODJvg}%pa&Y7Jaz!~w+4$~L z%IBqeELB+KNii)IS=AtKnpbMPc66%F#}dr)NPChCB+Ae=CPLjn(w;+S{2?eA*aAupNQ z#@*T~+uwQ+4&HhRwD`4y@S4aa1d8)FQo@UbB;*yb{;gC2=-}7%t`P1iSCq|HRJVI+ zpG60u7Ac*Nlt#aY)WQOV;ptv)1>>Pw$aboeLJ7<}McjY(6ixuTN(!$$fX3nAo1`uE z7G0S&1@feTv=<5F0BV5;9e9J}QeI~WKuLq%6Betk_bS(z2L^U z*EihZ9>}!&9h~`b#S(w+N5vt3GgV};ccANF9>S2od~QXX?tH!4jMl#RgFJ1m9z{a; zyTTBXWsA15k)EgxsM+D*EtwWh=62x@2zcam9uBTy(chRC#Pg^Bg?R`r97Fmx!Vd3n?Rm?a%!sh6EQ_`QbK!DO)dfklTI5>jPf?(cmCi@>)unuU;;uf~v;tFv+h`DOCr6}GXJ(Z4I4 z!*`__xn>`)9y~&(9~HF3=3CpXK-kwt93; zt^6dH{3TPtwIqs>iT)k~%vMO&f174K>)_4xHP@{N@mo`z+jdo3(8g7fSM({elw!{* zwXKkUnK~%$h(z~(?jYNSpDh1T*`9LPRxe_wSY_1o9MGlM5l{Nu8$T8T+XAz1$&ha9 zhwmti>{#C^BYRZ;&wi{~0;MX@DTHDoK3F)pqUzTyFkbuYLnzvbwfb^Pe}P1Pt-KRu z|9~?6AIj?M6tOJ0QCd`s4I1Y)E4liisCW1A^F67?y@Wect*eV+RQpVuU*SD7h|L+n z1L!aU&|}A|AK-DHijkqa7?rOe{XNv?Znfu|2<53?B4e1ih49gSMK8Eq_rk8sJeA1j zUlzN>sGWOKI|CH78)L}Ju^f)0#S>;!gE@?$9{#Yi-$Qumj`{vgqQ%P&%B5Fh_>&{M z#`!n(8=qO%wvSeBc!PF4KDm#Mf>}^i%&aMYYo1$%ZOhlfZ=e>s61!i0Upd-(sI*?t zb7H^wok)oC8mEJ}!r?+!`F^b||CtubBj$@Mnm zkA43GdcN^Z5rdEhE+Lfui#UDg3tOuU5CYF6-MBuR72I#Xh%I z`rku_o#)+;KVtU_E?Xfxzxw8SMaG-FWL4>jL8U!M$et4*@JnsS;7)3ezwdkTgAeYg=2cRS5OwU zm1DQVq5H}xE||HuB4xTthe)$rLsZS6&iMTurwxb5Jdg6}px#06^E@cZZ3}@TLF~NT2o&UIuU*8`4kSSmCZRyK0{V_N329FVc zzX2BK687lK=I(N&(79ek#U*$XICS;6N|id z_J23d_Sk~r$WykK5He?!MqV;{;ldh}(8jOYy_YMs$K{(=dC6U$56@sR>=nF+xK9*} z#Jt~?etU3(==@GTene09RFSlVBL&Xi5_{JESc!kaH6nW8#SuZRai{n&2dGvWxA8k2 z%H@soQK@r#Cfp01H+*tkZRDfK!=ogI|&UI))jpX|Lw^rAs z#5X8Bsd1)@=5X^Z7i(ekD;IA`BfQa&(tmxXgLoI&@R}XeOs&oGDo?$(9w9btD889s zXp~V`_hvGid%Ip!$c#&UT+`m)pix^)EY48;9kJLjzxr*O*-Xzm!x5uLkZM)4^e7Zx zspkj&Y3CctMke>kFZ{U-BOqC2s_YLhm%-QS!eSpXKX%TdTv>fJ`DtNRt&(ctw2EC% zvx#_zlfneA&$!qROAGgUT7dv-yZO>U*N&_*kMI6J8)>bF=c_^oR%;hu)FSA)T&9m| zY*NtNe6~S1?=Lp~u?qfFh2`oBRcS%c(TsCVdkx_`7w&{3uPoC{Pr_Fk)Mue4FCA+u&Clhsm|(1Ir28+knC+yqSB81E*3~noa+?Oat09!+mqJ&wf3Vc+S}cN zZGTSVtFzqZhAv0Pa`;UEM98cf41-IvF{!?aX$GYUMImPLK{p3w(*C+xnN3apv7(Vp z2-Lyohbi5l*@VgrhLJlP+d2KY?RT$0XS&ueZ8JomH&y5UIIsuO`tVarn^^YD*8Lfbd0!olPJtQ3FVQ>wH z5~}jbo@9?IPme}BS|%RR$ex3ERx|2EZkP&_`S!g)Vb7 z3%DqC8T2XbjydFxBd+r^NZF(AgxS6?%X(j$>W`^7EzZ?MI2iQQHf%`+6X%f#qRd6! zbOG{uH9jsz)hBMfN%X6qRUCu*%-5z;NZ&cBK4YZ0zXvws&;0O|WPYlqcuaU01aG@k zH@x$$j>GW}lLARIgeca4OLNbKFa%Pt9R(=#8{m= zT-?_sK$v{8XUS}zob#$q?9*VPxJ%R$Z7-sD19z9S5yGB-SjfUIs{S>W61ILcsFvlW zVtTj@k~iZpxWkgk-~*aL_m%-T8j75aJZ;`vqc_@ZYOQ!A-~2R)a&vu?&s3kvO{MdR zsn}P=v->??#*ww$9u7@%gs({}n-GwvjSkFJQ_dHjWl%p;%^KZSwcwocA{jCwvU!^i zzMTGXiyv~=b?m8U*-S+RwU6=GS1}IB#n(v}%1+u6lbe{9b{%6dU+ZX+QOfi8mxFlq zP`9KEhFMG3ixR$h53`8ur6K;?T=^rZR=-EI8(N zX$dXTlx`^rzaDNp;5?KlvwQw>w1O#DLKXOC8Fqtt`FJf*1zB`#De$JoYtR zRYv=!POY5mvVgKbGsj6krwR4H)KsBAYy9s`oF#X^6I0c74kVO zi8>Wo@OL|keN!=A^C>3yY6!pF)Xcc!R`FzeSO5J?f{6Qo{)xOK<*Rj=LJMLW;I$FJ?e(Xqb;yDgNCnTXm{`2Rg= zb(Y}(>&oEP3Q$Pob=D_Efpse(vs0Dfh*n?PnM3Gm*uJRK{6)x@^oy?vWH=&zJQ~7F zKoe23p#ed|78P0{%bA7;w+t(#Ot^)9zkR=Q*~lNDjASDsb3p%I8o(fEg#p?l>09Fz zPfil$ToZB%zbCJMIS``!9dG&kmyklEG7=Yl^u_u&t!ejhZQwWB*TSLl@6S29`3)an zU1XDwC0laeYof$s=>h5qIYb!%Mi)N=b<34s1A#qX-8>wQ!4eG&`ZbWpy_7hXm|lOKFLIh zyZ7?t89U@-2jy8TMb6q`Hx3)NITSRj+p$RCk7n;5`!LdbO+#M2JQ=-lRq_O?l3xDE z4{<*`;3EnN3kvFIz3Ae1!exNy%zKh+9E}Y_gq3e3ZBH1KOp|WP^!gya9mnY_MiB`+ z{S1?t`2dM+k3aq(x7|gpMg-R*Lf|npcmSbC1Xm-1VF0KL2BLS}o(zx|R6+uPu#AM# zxkRO=l2``}#(DR?hoYndRxLreGgnE=BOyKl1{>_ssRND;VMrK;h!+5%F;tlMq>C=FnV(QaNa!_+j8eW>V2P>#(Ix%X+2GBPOPKmGcGA8B}1lN?4(3qICuYi>2cv@_U6(vZW{ z*K-y2Wk&8F$Jo9H*~K(0NATKDi%6Rh9JFuGMFLt9!wWMip64pdoXUoR0}mZ^wQ@eb zu+0A1fxV*UXU=UWnHc}OtqYNuAUGs+ls2(8VSytU#IKX+K-KM;T6e+(f2$f|R_$S( zMv9TDIr#R}mXzia4D9uZ@}UB^mOi%eL!7C8r@MY^pguiIFIHjNs;h<`TB za(jUPc+&44uwis(e_3h*G)&<1m#23y7{Gl%Qh9`51Z+1Ge>eHF% z9XS?Vc`hw@>sXc1c#_tP@{T5`9XoTVbO#H$xu*oh&%9*lkLsQg=v5#pqt|o9-kgCM z{DrX%f}zT@OVr9$hq5N2z?vl>^>ggUVP#3ej2t!iX<#^Rd-fxymwKd|d$HS=rO-}n z&R-iXO*-z>Iq5k%3IC{VqHXkpQ(Mpx1`7P7`*TjG4``(}d4(Skqo(wgH91?9w}bRN zm5s{{Ga(L~=+4k1=#x$NS!&g0d?bb$L;^$*HpQER4{!bidja!u4n%XDrhARzG44uP zqpH?iD%#30$wEWjzedl4Oo^)WK`F#iFr)a7gNR47oPvwGYUb8Jj4l#?mxkApJ8gs zv)9o&uSdF)hRdH}Z9mqr6V)mDHV>z+5a zs)S}Q2^f4`wY(Zi|EUdo{}HyKjJ>v+)W_sH$TnUYTF>{{MC?z*;U6V#d{}ON_v0ZJ z@5eL73EVH-IEug&Hf5!|$c4j;*seMF|1iKO4g3^KQI21M-VQ7su$*M4S{WdSA zbGAx4$yhgXhb0UGBUSZ4V%@~IHo~HQ>ZJ^BmeyJ&bn9+wPtm04aP0Paqh@8B4Wbw3 z34(ocU2RAnvynW)L5u^pO7udPrrm|cbR5=Rv&%uNYugLCLF}}i#0J1pHojPfDOqh34=qwWb5Q-(yQwju zeIm{}=wMc~BW|2dpJbIx4?uC4h(C(oK{kf{*nI!HM$s^7Svi@iml;EV4BNv-1ND2!Zu&SsP_06o?^ zvL~X!T!*6on{T^4Tvn7P&XKS|E$#WzFottOkl*uNS3vlw4oqxUFyQ$R2@61oQ_+8Z zU-CE2>ZGiSm+^c8dM~oV(Fxfz0ds7hRaw}K`iF@pXT^p4<>+V4W zuWjn*eQcnOwak5Un5$ooqcO%ElXM_ictEH+sO+~(nmD+W_x{{q!JAWbLR5k0cno z*LohMyxU2AXIp>o)0xdTY@li)a2R0|ZKeYC4~$vygiaOhY&@6hv4ZuoTE6_}is{u5Z^=*3+EhzAQ&E2_=~!wx;{vn%wuI0q-c&C(&x(vBKV$#@_@! zNjy&3Sy}rwIroipz(FwO$>`c~)#WiraNh!TQpa{eY2tB z@efu9u!=g%%exON3@FaLfk2lev{wRf8kr)OtKy?Yvi-u)I|_eD*vdHK8^^YHVeJd= z-c`XmWKODkYR9`AXzeTrS+FE z{_*7!NUoQrwP=O`89oAW-kXQ!z3i(ac(qQQQl6yo@z z{L>0Q)dQCeh4(oRE`8};C6X^#U+TN?X!ekVeM%UvD#KjgAnsqRvhH~LT`-oA{P3#W z7yV>-DgC2sYzYVi6rG6R^xEX?UK}D`0NYCMU#A3KH!oE;!sicu+5x^gFMVBj+^;J{ z*r3yqArTlG@V$#H(gb_-x4hr#t{4vTi0vBUi*}uez9s&(KFb~b;-c^(py3?G_DzXe z&*A2-SK9i!Oe;7m8?oRq*c@YLU<1ht2+GO6@(px14sf-laW1s>OjffMbqE9F+1`@? z`_H9-8?k9O;2_P-WF>2Yoye;v&$vhc}Y3g&LJM8+toIb1?^1%e=WDO(2{pRemJWifRhZ=uq8d}jJ zs@c|FPk0zBeDPE#w6&5D;T9Sh7)t&HdjP`HFpy9Rs--9pBmXxc#g0K6{YOYm=+OQ@ zgp?&cct(wgg6#Duz85_dC8ZUH6vkkPz;J3omyHdgNNP$WJv_cw0YXD*fWvIydcq;W zNP1pj8w@6gRNpnqMMKpj8rL2D2*$6r7@al|ZmCzywL(VE=)e->Vz-11JUcx)`0-?& zBTbDmkcsX?#49O1LUdiw-7lYtZq$HT%+Glt<$P=sQ8jEt4{M33rS8pUyPHo3y}y)Q zHny>BrDvWY=i7&^w_^g%z8&Rnr7CjDb7ICQL15xX5o9{;^d%Sogh21^r@zsop-C_w z>}VQ}s3d)0$c4$gr#9=TUwJvQ#6e8kXg^;6*ZcPR^7|iW-*0AVu!%6>h&5>>aF!gw!QJ51Zh}$X1_C# z^+IeZkVDxFOrH+G(ZWVF&hT0QXO@j$y7&7sC20^K(>t0fGAt=?* z@|gmE&c+SQ4S3m!AKB4RT zf-V@+B4*W9%!-vB#%4G%8~ijQei$?~p&t6M1_dL}*ay*_sUy>3d9tK#H#;_qsF**- zLyPAwvt?`|gOdPd(_REy*H7d!0`}C8 z&wA20M7Wn}F|59s%(?xsS>^TOrC9?lgQr%KdZS7kg^e>qz}n-v#lSPWsJ=8tl#Qk3 zgFa%yC#uFqT({~+b2qPE$%BsT_G6h*DC_y%^4r#wzM753wAL&7e$$J=j~tiG{uf_& z9o5ty{}22!1`M_lqkD|*Mp77^3W`W6-5pY*j?vu>ItJ3{NNGn(h*BaYA_9t{BB0Xy z@%es#|NQ>>z5m=f+qrk=+;i*od_I=S-RVQEACkZ`3NG@^hxs4Sh}J zSJk(~<1H_@yH?AQ?LQ(ro`ma#&OFs=)3Q%!y--zq9_unCEQ#LBp4H=7QacLhwqki0 zY2$x!cesXkVcV&%Jlf%PKou}aalEJd2}_V7K}gsLKl4S^;O^c~>1fJEhSEW~{bN>Cj6S>L1pKC`Q+sSM0wG}65RAGfM>}PJFPmoo4vWF5GfZBpVB`N8j zt~Tp*;ulVq&2$y@g9Da9>g_ z=V{npi5Py75t0B;PO`h?j1@J?3K^SjaDHMlYSPN)M;Z=PJM+hYFuDoyTmm9PH0k=K4p3Fp!s(;QtThl?9UL%UE}%@#wZZsB6?NFsANH5qEjJx4IP zQt@+Fwt8gd_0=?LnZnOzOZyKZtP?*``s2m~^X zfls(oi0|NcB_If6?mo=reY}z?h_0r)t zL)Y%IlpFQcrs5dT!zwJZIZ=(4wC>7~?ls#bR|UUyPNnydjiph@?5TiLole)uEt~9i zfn%=mP!yO0SFoA)s!H6I+y+5LkAdCjylHx9{9<}$>N!8zt|8CzJ0g>kKw`UygB*=b zd`G4LB}OYj41=X0w2J4vOL4!lq8_+oM7T44$8^9rXYTT-ZrBo(LgRBz+=w80j5v~H zeHoW8XvMewG(6&9Y)YAYAwc%iwHw6E0n+978CUU>|)l#1EDN%l1d z{P>Q_@SVbxbvEO0fuH9|B(v!gpu+wul#(c+YbXnMmx*QT#!-kH{!Y@YMZ>L;gWLph z1jEnEQav)ic=Xa(`f!aY&DTo93zHoBEA72qmUhXKC=5tJivm1yDMhD%DCRp*-O5xY zbB)`Il`34zMY6KKX)fGq1N?_g&$C*6HU(0DSJT=6=+FCrNMcnLcbG?Foee@syN*+Fdm-w|Ea@~Y zW|%G~W2aY8%o4cS;b{ee;(5|FkELPg<6q4NlKQV63fz;#WAb3}wakrxNqS33FUpO_ zlnJ(wk*9b=n$*ZFdK*lJfP|(>(BDXs;a~iD_kdSjZlkE}Z{NhTYHu}dAe5IXZaUKR zm4quh3zwki`-jBmSNR*GZdJ{XY^GMY#Caytudlx08lz#tEP3_zeEwn{YmmdKV~|?4 z_K!s%=n4wMXT^lII7$CUigQ7$2O_|tlIO9LkgVA{KXlNmFv)As3i zcx*3!+hZYz?FakFlt28#q9HM;w+#A;(u`i(Bp;!F@J#i^<_xwu3z)n=$+Ks zh8Xbd|5;3)%L+;9LCN4V3MQt@WVYGumUJ+40yz6#JaCcE@(|2=RTre2sYr;`B#;Z- z%~X_#MYaudNa=EV+p11Gsa6fC5{J}=`KmuS8C0zrrrnVFQ$b(68p>R17{L*1;{=(( z8*n)rwjp%|v}Tekkb!XJVQq=wH-as3VB9NS@Cw%;xqQ72K~~37)KU7_h^Ga=l*DCZ zc<25A%5V%7OW|DmbmB3yL8^L;w8RkO>UGtQ;U5yi`~asa1|{F2g8*^L>XP`M7*-ls zmMi|Ht(4>#kB?I-;JOmVubdFaB$ZjqrC!(4t*AT83#NkN^QB+%cp&&#!8~ zsp`ogxr*mDy=#$Ng%Wc!;(2}0m-{tF*EnZbbC%QOVVt;srC`NewEBQBWYCNwjt2Qb zdm6;BP+9T-WwD08!?%TZ{A3{KcJs#M{sZt=JsZoYVapp&*W$rSJl5#tnf|z^Xk{%x zVfbnMdP$J20Sv{r>}-%0V|Pu+&8phXc3b;sNq=6@aMjIY`{~`kq%Fy0cY`yxGlt8t z>o^Km9vy*d=W2GBhcjrbuJ+G&ZfipR+tvO;@2u3FUNp^;;@8q3bY3W;!PKm;@5kqT z)g^E{16M&L<&^Im!FB~c-V^uxN4&!^+xle!*DBVwi~yH*&X8)GUX3reCQ41hmP2oN z)a^PMS_|`^-z4$n$~jF$wsTVu+;sx&Bk?wKLAtjJhP4n?_xEYVmQ57<%iR6lsa2hl z!C!P>S`Xjk&>(>dGOg8fVV1aU=$3vI&)3qu&w=qzu(OsAs^f>U9Sva^axUTZY`58S z;gZO^2I_)b+3sUIwMpGZAKQ71f_1TvMN-yaVF|jRONzpgbcfPVi`@6g_RLq6MG=FD zZ4X+H%#tZof>qYtn}xREWR~0Bl3$4mB0BU`G}c-;^a^N9M9*+Xg&-2>?@>^aE`>rh zMtkW+I~c|71ZImG5NizRiMi7;OZUJGjxii(1N`bBQ36QvD@b;FQNh=9KXN#wno8No zv%H^Lss(9JlV$&At~RPJLN6mZN|zcCW2~oS5cq~y5)+*UHBHo|RD0H-(p*}$hUv}g zyoU=O7CzRFdy+Doh2Y`)RNuDg{bqiZaP?W8H4m z`hyLFMRSJ5o2$imHpB;usalh4WHQescH~6s8A>zx|V!F(n-7)XD{t~vA-nt`iZg(5|Oy9jV>ODM) z9iE(Md}QtQVe8eD_b}#$+Z)^AH(@Ssz2jb{3_sJ~p0*lp!`9DUgLgriKDItMvL&2RZiuqd!f0)4o&7jaGYFOub~tyg^hi8JjK{eT0-1>X}}i__zH;+{3ue zoVn~AU8Z&H?%jahjX_SN^xCuWwcxm)Yj=zQ^jI89b65F}KHJ-+*Fy8t94J%|DZ zIq3s_Z^&|34k}4PkUF|_SB5#+TBzU48W=s}KX|neJlvgfZN_St@uu!pMv!Pxv(6qs zFM?*$jbXtIh>(LsJodMo{e>R|i)6~Nt;+Iz|NVH>SLf*WV3aN!=WiK-ScXE`Ln%2u z@MV9q@K<1WWE9MnCqwxeOL?8Nm_gqv%ik(T9v~lr719h*2my&mgVwDMWXZ{tOqz2d zz>r=!S~_wC-yxZGf`t4hF*RNBnuE8!zx2xd^~U^|y(#EdWoQevSxC2Luo#Wc@@x!`~G^h0GMutMa|Mg5A-Oqaxd54M? z&H91zH^{4&P5tyNo6rgIh(M6~zd^y+0dpw+v#PFCxFyHlfUNL=T);iekl@>ie@t`t zxy55xl(CjCLqLfka-pP->%v1aabfB&$!zcY-ub0Jmf=4CNm2LfJp+sulf<9|=Fc9D zfArJcyGtlp@&V^B2i83bns1d{8?dgq_Y_mxE`)}ZCH@7!8d6ffqL6fO0RsK(mDSxm z^a`h7R4ZS$(w$EMuh0eydZKwu?hRkS40MJi55$1oumI^0`P87`%m3+>j=Ic0Wi4{b zx2>Z;TPAJ8!>9uJZ-O)WZ-(m(hsR#=dC{S-20q}hJ2MqV7VXKf#mb8OQwk09c+q}w zBi!{QJOdMf3E0Ny!~q9C5Dm@YyvkVV2%R*k=DsEaV9??16DFFM^tIw9o9bHygA;a|q7vR+ZE4z5+tGtw(hIi^8b z&-cm^$8mOPmkzO$W$X$i=a7UwwV1BtgD%^oW1T9ch}>%C zE1_~gJ41*zLenGGLAP=xl9yExuy1RU5`Rp3{_hzArxS;h2d59o(Z2T|6FpAVRIOr6 zwZ935ALLeD?=B2DX3YdcZr4509L~}NGsK?U9Qva#&^h+_WZ;^tq7^~3FG?p+MHks~ z`)DNjQTH>K=e6Irs?~IB$khxS|6TPCxm3ia+D@wOt38DVJuY2GzWv?$N{XgblH9DP z{hwT2SR+B0q|ofcB$;`7P4k$I|2Ml&O?%BeS+|c3GKQ}RL!F2DSrw%>-LBUd<-&en zr>G9G-lHqsU47yHQZqPP&)SxY$PqC>VNV3h5XlG}Og?Hlfv2J zE8VM;k(H%<>0zf_-Ao^La!(8_8kl~BxqRhCo^{sq8f{a7v{S(z4!?aUAu;3PzX zJfx6CFZ9%+0~Vr9Mf_c?R5E{c0=imM;J&3tT2NEWjC@{_W?T<>!#Ftrdo)ZYLj>Cc zRAU&b2n@`Z2rdH_SP6(;GT}05M~`P>0BGbpU#E{om1cxtghqZi1$o~2QfVJdSL;DL zsZVEh$Ac_FN1#c+NDF*)wng4Y)kdV$B`#k9(^>!J%mc}%wy?lDn(NiY@2gb}DI3VB z-1m;BwkPg9>7(Q#O0={R_2rBp#LG|K(mk3!IHxEBUY9881wA;uTYT!Rx21Dg_J!Go zq88PLqZ+pD(e`Y9{ zWtM44yL0$|2`MWubCt*?9-D(uA6EEEK__W*jcr|?ezcl3H~2CVL#n)%Z#k}di2DSd zkX0<5^;MPsV%HV2vtUMJ{OV4Xncxo!RVVMI1RmSabpkpz0m>+(n?%G6Br{T(nue+p zypXSTyTah&2N=r%Hw{x6wA|)Od%%a~d*>WsyV&Y|mXXuHwbKxofq{s{1~G;)i(9@w z5Isam%kA2hHBc72F_O+}AQgy<+sX#zdcSGBGeD7XpkMKYJtwP7$+)r8JZ0Opw`rYSQ&W%BYC zo$t|T=TwP2_&!@jQv{45r5zb-%_pm_S0W(F`9u{u%Zzv1Fq5>gt8PtcI7Ea?U2<5d zOsMgI(vf*({~Cg6(JB2y;m4GWuXVNjIps`qcvGS)=?&y6g_!B(j#!D1$xvUr#&i4D zo>75ncKm0@#q5?0)e@XBWt4oqqUil&Z2iZAJ5otCRTmFT){Uq-+Sc(LEPo`E6cOv- z7A#q!XV{r+33nK_qCWnvBF8(Wmnk=nx9X3lP*V6nJo`E(K#FGRMZvq`*A)|g4FM6I zXF4p8R3m$GBW%2#s#@c*B_fPq~ql)hAyEee2MVMA+VO|kKPdo!e z)bhrutyzcZ%ANuO)I57&Wu`$|b zLlVJzkK%MU#h&OtSq3P;0vI&h*W85j^`+V8S~;JDm1dp&EnIvy&M7LYM=DzfvEQ5n z*T!>b+-1n;P7@NZOU_!^0YBs?8-RLxnFRD}6{0O%r6b4nO)fU$mB`Q#T`er@up^~H z(E!vQi49zi0~n^YsI-r>SnM%m*K~~FiL>LoX00XE6k1At!Bd%?xYD)5YUt~~#w*r& zW%*}D5Lb2!y9FGj0)~tlw8zLOvkv0)%%D<7lEXz_yUNMBqpysQdx+)br;5|)D55}_ z#%%?P^ysbK*cm+zW|6e{Z4$(t+7dUrPVpC(!dEmcPKL}9Fi%6tsMy>rYnhEnN#!x_ z*s;V7Vrn(Szun2I&$gZ=HePE&!-A>vlxRi@uWx$G{5!d&D@KTM5i|na>2C+ju0K|) z;C?$lVcnuVPjDY`b7r);)?=$A5*hF0a9%R{nSp|!L``PT??cWJhjGHXv0e8Yw9Qdw z;uARX^71o^WoWBwx@sYISJvl!NEl1DKGTH9JrrnGzk^afi41mE>pH7e4w#=F4bj%J z!M4%))}N0%PYE%8o>h7#Dqg{R6Y`Xkem@b9Nt}0f5|F?GH+5Jt!m8ryAwLpB76CW0C?~QAvK3Ho&qrL=4O?Vs zu~(XEt%H^awFa2T(7>XN1FJpR%M*B@I;mmxT#5B%R^zWwMpOC?rHJ^eK?Hq$89SQy zEbVfi{B3={py(cT#@p`V#Ei7DpG)#71t2u{8C%}4=v*0}tKyZ;agcsL=aRrYmcvNK7q(hPPf7Lk?QF;*uFlI`=i?zi z-+Hx;QLg;HbDt_BRjO;vANOTa;Z3cyum)o%5w5H8|mC zOvC-R*0T%C^%*_|Zo&E%RL8<=v=dpcnsl8gpRTHs#X$Bs0})5vDc_P`T-$CkV_`g{ zk-7S}|MOD7*68{K!VHA+%t&%GkKMj}GCkN=_a&j{y)Z46WEns0?-Wg$a`cQhcV9gt zHbFhJKlMdlF~@CP>mknzNNS$xo%T=Z<%+hVo`dHinvC8i~E=o692dIUFAl*RXujcJtw1e78(+j)9eu|#~ zUmDG%-h`@W2>i-c9Fp_S2G1Szez8>=+el^y-uK+4xe?L#-GR9tR^TnSS+Rh)`W{KDM%C>nZ@lPM5KfXFAVq-5CSn2$^CojOlbw~HPIo9~8hkdI3PZqC5W zI91QIn?78mpRkhlMks@xQa)bq^1X_XDV!5tiVGBYnE9e0iT1O>ax@;2f`h5YxF4De z2|QaFHXoPC78o-Jm!u4`O`V8fVd9{(oC$g(Je>8nTc@e;pd&M3fXA7EGmH~p)-v{=uQq3TA}1pra<`d_C5NwXfIV!0YwkCzhH;g>BRE24HDZQ;lR-pZmOo>L zhcEu*DxR)thWB)a-COpQ=Q@(y1Id8moBSkj-prL!K{q`k3QBE2_+NxOj?p$vjY1c_q` zh$3F#K#t|6oCs=9(q_7N6CsGtmMw0Pyr=ySJ18wkmrRo=L&tc7#$5I|Tei=M)hY%d zQb9Mk&XtOz%DWCl$3gha!@OR428D1J(8rwekwJn~dsq2a2L7 z+2%oYjSUI7Gw;fQ=5b4&KcmK`e3tGZf3@7dU3tx$0_-G3ti}Q2s`PgxSOEr6;Hqq8 ztDaM3ZBy-PWk=>I3g)R(2hv(#p>RA^3ZL{ZGTuEt>5q({8F>x8I9&tF(;J6w>TtSy+OYs>dt!?C(A2*1!JMI3z|lrY z378YI|7)$C`(R9tzdxT^LtD~gpQpu&_iW&9A(Ob?g2=gaK!O$j-R0QDDSAXU~YTkPW1irny2gRq}Iikym8Y3&8tnZ1{ba@YfiWQB*Mc zgXZ}eCfOJBHbu_&`3RkgOd$V=uAg(@11z)3K_EkTsN$d(H3}xi;uFN;+T6l+Wa?eB z5PU0+=WSrfO)#%fhPnJkh{lV+@QrY@Le5mc==}{N_ExU4-~pDxAQx6X*N%4Ye_=tl z&BamSTYll9_z>#%f<{<`WucCRTmWNIq@uP{c#yw*c+^d>mEX-xT#K)30-3Q-k*lE02kMN~+f-tdiwh5ldy0s$ zz{e%F-hX8f|1p+Imy9ioj2&OWJniT`ZN)F694qUEakyn3z#JL!PWTz?{RbY22B=UK z`H0v>;lJw~V*}jV18L)A>>M#vVLP68l9H)e5~v5Mr!g5bIK;GLx}WxygBC7A%ypMP z5B>>1{LYx>bm@mKrZFz1^`M#d7n#Tc-DG~HlM$&oKCxioB!v&qgW&$G}oj5l}%l#~h*&CGeM6q37qV`!xqTx z{$6~=BK{+m$~LBolLMNEp&GXFcL@vgD#U4MQ~MTI1$9;2v-MPD%_+3b5mc?tb*}d5 z=9KH=?2h5;{=|Xjpz2U|vID)dTCKCvU{esdQG`!n0z2P^fhwhcYDOj4y8`C6@Xs37uOnSZ#RfG(bW zbY&0OQvm7H{tb26OX zy!!(qpJUz~RPeBH7gnOFe;%ZYZp4ru%>3YdJ+vD6`S*KCjf4hvKIMpnR^d`{=Tb7Q zs%-Wd#s|El4fJwNA5Xsu$9h?~cv*NrA1e4&cNT)!*+J@AZGEVuvc#@)n86c=xb9WSC_c&RtAubNTNP44CXu7r1JerymC={ zL%&@f|MX7DssV`YuUa-k-*QC{1Gp2fah^xn^~m+{GYdOu8XoHeOQyT0Ph7Y=n#&#E zen2(yeDGStIPmNgOYC?NC`U2{A~2uyIEz<~ZKdN%G_QY$c76|U?+*XgeUnp=c4;@L zi?eoZn{<4FEMq&SfB1Ff;s-TX)l~0mabqET%om?-<{Ot()Y@mw$09TZ2ZS|b+Jn72 zl8aDK)RowOMd2aconN2WS2g=nfO{V9>%)1>-9nSjlJFt(zCiJR^I(6E8f3$k3RQ( z@KfwZUV9;PUc=w`(R9E(=OEFptUamY}F;>dc>i@w; zu3@p+b@GC1Zrfw3Q6=&3Yh%5yX2RCf3dSRQ?(~(K4Jjih2jaJzu~QsZ)7YxXD5&Y# zF6S||MwGn5@l&d!)wWMGKX&Kem;XB5=Y0Ni-sz9GQ}G?fo`-Nd{y12h&)g^h529ce zy(DF)9m!n46iAc1M(iPOlO^wzKJFa5uU6n&S$>qB2!CtDxZEfGb@g*0?FMiAKAH4gVfWO$#meEZ7*xm|K_gXki)LE`;zYTV%<4q) zlh~{V-TygorOXwCA!c(Q|A_ne;PgXYaflAt(Gmv4QpD^9dt>NgDrTAF;ztc2(HU2- z8FE5dEVG>M(-94**eRLlmrPM>S5V2qqoKtqzClViL#O+c=k6&!q!uz{I!fXP0jq}Y z@$P?%s^fLslR#j)%PbryU1LE&H^wzPpF5iN7CuksmP+j-*=7iL!E6w_du4{zv{2lo z;^kgN#}QcllVp!^v-9iKj#cs+F#4j56=zM>KBQ+GVwVBG z4x^5SuJ&V^#_qNm>bjmu6qL`u`!|bl;(iQdwoQ{l`^WXgzvF(UG5xA;FFs{V%J}}A zrF8D1GZ`HmVkex+lmo*JKdX>N!Nb=tE;#qh7dmVSrc}`7z{!u)jzKys9@AOFKX057 zo&!}4&qjHT@Uz#DboUI$-W90NjlXX(cAk*Z^jiSvS^?m-EV)eUYsM><%{{7*z$r%B zRFZ8ox}_R(V zueoTl;^8$tkEegH84smLT2a21Oj^4v8@#ecX9ZwZ>978dqq}+n?K+{y0Q3#DxhjD8SNE|Xmu46^_!Iif#3}MIa;Rs^EWqXRcMng#NO3>Z)sHfoHkDv2 zs$h~8GVnD*6hjQt71q(mLyr|3EnZmfO{vqFUyrjajJcji(6$P7W)W}GlX%=5k^?S> zX`)9Hin7(O8gdH+9gb#37)evse|FeqV^pW5jE!mB(&q_Ol}2Ty(**;q*Aj`{=-+vp zUYp1u0VA$k`w?TO!*WGm)DL`rr_gO^|M9HVaKOx}3xmf)!?clXBai}_u`7tHTl_uDpdAfgwLngv}9Ax8!dbV5}9<^t~9c>T=ls#2;Ozy zEKtr^sG%&`t4-&PH9n*qS(Vkz0${?nYxC@p+YxId_Ui|_3;_!(rAWNZ%-W1q4soUbW1_GIukyHW=i+Y4GSw&Ql;rVNa;L9RpL{Fs;y7hYjd6&J`#sj zd(n8%FQt*k3)|%{tLn7)H%+o4Qmw?rybD%Oa+0vE`Nn=?H+ODHT+{G1pw00%lMjqfwjc3&e-ANf|Ei_v?uU{0U6H>Zl?m*| z&c-g*qXOCEZsDxGLKZVUeS|U|G+GPX&&AzfkusQ)fULZeHMVJNr8{lx3Ik*M3tkof zQQwrKG2xk?Sn!i6mh>yv7aZ#bztFx@WRmc0g(SHD+MaE4aWtV+G`u+3fZuJ+M;^19 z379(0H%Wy#waDdr{S#cBY6>4xQ!g!sdZ?V{kF5WZ$^4{f{rx;?&spwcd-6y(WzTaH zZy!5=YTp~gBLj4Ax0e_H>;1XE_!h&OJDzPSQJ6YTyzBO59gDvw!bo5A9sf+ zSekpHN3-ev(vFAU<@rCXPN@v*&CE@XLmh>BS)*S+3B7C`8iJ4&P3{E^%LesF6+-|W` ze0~joP1F79YfTmTGo)m$0@d5uVs~$4QSUreM&cZ9TOO?Mrw3|WpD*EP>mDrpwpi|3 zxqUEUeZj_PmpK)i^HUKi&6(?vsk=x?xY^8$!J5}yo=>bhBDo;w@ITX`Z=WICHG_XG z-?=Zc=-);a^y7yu_R6#Tbn(hDzn|Rj^~GE6SD;1d{M@5X6(8^Q@u zU0GVK_}dDeJz)qO0)G#wX%N3YcTnJJ|Jl*Qn;v-RB+T#eQj%T8ZiNH+?eMRlQF`)% zoAWi~-v|2~UOHvubRvVScMpuD)y#|gb8^GIev5ml-`efJH_>n*W7_{L+4+xT1@^HZ z{z~UP^Is9G&maEl`k`cE`%7TpiR)!~vidX*&1XYnMT=@?8Ac_%! zg zQg(vysLD_#BB>LnDHS~9a%=p${>F+k#2Hw{T|eSbrH3pL;csy;2N76~<3sD(sDl>_ zZDBsE`U&#RRI>n$r51&a3}p<4W|00Nk^vm!nBZgRa$ex)@-;TP7RfjOh09VB92wC7 zG#8pv*A~puJBUKJPps z+=i(hZwFPrH-!|^vStvEXf9e z;G75s#JB>tSHizeuD#Br4q}$=0Mtf?;T?v?K#QU)3u;6SSOPS)08I`dt~L->OU%2% zKuTUO%5~Y1Lr+tNX|cP=Q2sHbFhCZ-E6Dw+8MfXdERisi9r|}gaDrAoAd}4(0_nxE z;$8N;w2G39Bc^*cc_Jh7ek}#!WC2) zRbrH4aIot2TzWE^S6M7ZY%;ZhIYO+NVMwJIM`#SP@S$#r9}@O%54Lpq-5Lf1LP1kq z@uU%RPclmk03F28%oXQ_Inq>Tb@Pru@OG+qd27b@A~a#{v(bs&t2 z8b}17MN9OxS|x-)SZ6WC1OVMRrq40Ydg}-+Iu3trggXa8T^YfH)1*Rf3wWvxe5wcz zpD2;2AP*iZP(Kboqb`ivPxz3N?gHe=I6<#d16>#zw0yS6afbdJTNAmLTv1uITO&>}wIU zJvpeGvEFi;Qrftj8(kuqjhiJVcd~;AN*ZoOK3QjnjElgq^}=5}YcjplXC2EzmMCLn zC@1Rb|J;yA%j>NGffsfmzJrw=WNt@AN{;1q($i=slPx1c4*Mr)rA?qB!cJo?V~I z%NU10{A#wbmw*lghaqX{jx%P7=m>Vkw|nrV^;QjW_+7SV>ST!;UL}#sj09X2Luu%{ zz-;<#ipg(?39UN8<#hM}l(8EjMlI*EPRa?dYocRFi*YPwQK1wmZRu}MetDAPkVK$E zw{i)XVMjA@hJR|ARmvB;;y5^xLz69+*eW$;O9GDw^LX+JpoQyqAv`EQ zj6Rd?JAJ)q+1ouBoocg3Nk<10IFXp#wf>m?4}3qVta=ZwqgMD4U?3oKmH)v8*J}rM zir*38MmDuxT?IB-wajrW8r}?kMd=;Wk88%@jV9UXxu@piQ0F5A4`=0;5yehzHC;@S z=V_OjUKYbi@u`>i27wEWd(we|K~id@D_|e#+a~rJ3`?MmYMrW>4pqncTF1tplkoLP zgqM_p2-YAcYzB27Mvx42$xM23IcbnAX++W zGCJeJvfxKF18PMSgGky7M_Srl=T%~9w&yTiBzRU!i4pyR!HH%G*VXAmyXKP?`K`y# ztBu1phhq#eF`d!J4qhmFJbaupxZa;OPODTpEM@re5NaW#g6~+54=ANrl|iAkvLlT< zV!PwayKuvXJ;vXYmWpfq2O8krX&Za6B5LTY45d1Ce&7+@sq~dn3B|pm_#+>im&@fg zjx_#b5xq#H3yuV<86R!8gAa<9ZF^JoyzcQmt}==!&zT;79^FsRM+;M*7+lMDqJwk4)Fg27FzY1c~Yp*~a^k>Ey-4#|2o0}PE4 zXQ2V~apE3qnd}Yu)C~M{`zslI7d??93NmXhXOjheuKfHVw9|Gx$J=R^TXODuTwHZ; zHp^opgVvT5AbF%f}FY z>zBj)XH}!6^QQ2Hde*|?>=YIlFbAvSH7%8lDe6EH+KzKv>*t-!-Zu!(G+8n?+cE4Z zKRq9ZhTM4{^COzvHbQg?E#$R;ZCZSAMT5>T; z8>ww;HOa2+MMNg0cy<-|i7u5-EpzF0kj2JT(IkFU$*B;%>@kB;+mtm;t@PBiK{#q> zCTn7}R_`U{S37p~HLZT1pWqLMtRkPhOH$}XPE7iJXb&A()#{l*(r)ZNdS@=D3XHrr zTU+aR9QqoXs}jD1d+vv%=CWV=%^fImA3~j+{w@pJAo=ms%!LS}X`K8>_PCgg?EeL! zXhEEy#7h_opb`M6;Q+N10A&PV>Hrfnz=Q-ic>yj-03{Cy2m*p?fP_9EDFrCp1XNT3 zRXae_1<=t2bbSG%5Wp-7Ft-3K;{m%Yz{M4CDF?i3fuP_^Qy7RE_z#VWO8^q)fz%Zs zD+kE=0_1-Oic9~~qpGR_LJKf70=#|$EGzXVlN)G>DF^Z0Yla3$4K*__P z{ucp8T#8Xll2B%i9acENPA$%%O3TT~$wkG5G(_-0_)svlOBqVYl3ADq5TVl-A&^8Z zNTPRG#m-5WM3kf}yEIf1IS|?`OM>1nHGsEI6+9du{pNJ$&W=qRZ zl4YOtE#BN)=cL<1GS+f{O$5n~uiS1@&febsu5a4ic|`|S2d70P=QnCDE-tPrfU8fU z+pxB~Ai*;nu#ko)>TwA8|-@`SN#h(X50 z$b7s6p5kXo39?@j!kv>ZNGbBaQVidv;7Dnxw9A#H{yTetlw%3}uliIdR9JZbR{eV>R#sVA`SdoaR;;%6BdN{_sJkH5cmJn8wS|x_v8NZ3FFNm&dU|?#w@H1zz(6W# z#B$_vjmeEogaVh|(-fXG_v=6JX5IyjFY&;o_q2ON zx+I@|hqPRhPX}5D2MN80IYWnshkr82|5i-?ZJhc0k#y9vbUg6k7x0L^D>rl`4SIy`O{8+-it#on+RCAYx|9ac=fUf;q?M2Y%25EA- zH_;t?DdWjHn%B6G4?b0uJKUCh5cT){N<%7%l~Y6g*4AYEmFsjD_kaA}V=N4JDC;|! z{r>y=i;q|PA9WvW{o{G?=g$k?M-*#`>yKaymzj^X;&7fAMDqeiJTw0NdIGJn$gS{2 zr`o(k-jt-g1g>h&jW_}9JA5j=dlKrJJZgmhQe) znMHf=^JcEOzUWrohcsn@RPkVs%>vDzYy!D9&g1m?t_3?)`9>G_o)*}5u%oi>M2UKo zL5jU<@;no|W^z=!cRU=tKpeFtD<8bR7W>lHmp-;R-x0A_!A5SD=7IuiD5}sSVU0`}+7vN4IDFgHe)LL%mChw@`hhf45i~&H3l=&xw@cyM$pD zpWWs$A!wt+4VZiyN>=f-5eKC%g<7X5i;tKLd~12lt?3ME)S8e=&5_!^dg!XMi*xbG z>r~2{lpDSZ5pSaZVDYp6jN^1%`26DFIn%&4VsGH|qEy0s;^77rar7cAQS*YW@@Df2 z2nQJ+4Cay;nvgp9rhUC%r}@gSt19$DOfPo#J9r+YQFo1|nEKTwdmGEQObb;*28TId zhttE?cIgIQVWWMeE+iOR3F`2kcShQ$G+GKHSAR6jjx9&e=k6R0Wi+kfDz7Quq8V

    r9O0Npb6O@lm(B384k{ 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%0DhK?f=f}!}myzy0SK= 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ПXa~Iz{FPEaxxXTiUkb7O(P8|xt0Azzh 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 z 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 z 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 z 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ⅇ(+; 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⋙1 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%0AJc*-A`R3} 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

    >$OO#;D;5WaM3PI?+N{)JqlTf^x{D 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˰v}$F)s23MZaE<;Sd;e(Dk>|JSYIGWo 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 s2MG5W#TjK$Io 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­3X+{3 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 z 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%0AeNpkPpBl3t(mYA9Ke5ASwnBwfc|Uk#z+q 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